@thorprovider/blocks 0.1.3 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# @thorprovider/blocks
+
+## 1.0.0
+
+### Major Changes
+
+- f011717: Consolidate the `home.benefits` feature family into one canonical `Feature` block.
+
+  - Adds `Feature` (export + `featurePropsSchema` / `FeatureProps` in the contracts surface) with a bounded `presentation` prop (`cards` | `split`, default `cards`). `cards` is the former header-badge card grid with per-item learn-more and an optional section CTA; `split` is the former split layout with the optional grayscale image column. `split` deliberately ignores `badge` and per-item learn-more; an absent or empty image `src` renders no image column (never a blank `src`).
+  - The storefront catalog declares the two presentations as the `home.benefits` variants with `legacyAliases` (`Feature1` → `cards`, `Feature2` → `split`), so existing manifests storing the numbered names keep regenerating to the same presentation; the benefits feature's `compact` / `detailed` configuration values are unchanged and map onto `cards` / `split`.
+
+  BREAKING: removes the `Feature1` and `Feature2` exports (components and their `Feature1Props`/`Feature1Item`/`Feature2Props`/`Feature2Item` types) that this canonical block supersedes. Consumers must migrate to `Feature` with the `presentation` prop.
+
+- f011717: Consolidate the product-card family into one canonical `ProductCard` block.
+
+  - Adds `ProductCard` (export + `productCardPropsSchema` / `ProductCardSpecProps` in the contracts surface) with a bounded `presentation` prop (`classic` | `minimal` | `rich`, default `classic`). `classic` is the former `ProductCard1` structure (badge, optional rating, compare-at, add-to-cart footer, reduced-motion-safe motion); `minimal` is the former `ProductCard2` lean look; `rich` is the former `ProductCard3` overlay actions (wishlist heart with host-owned controlled state or uncontrolled visual fallback, and view-similar rendered only when a handler is supplied). The comparison-table surface of the former `ProductCard5` is deliberately retired (a listing controller, not an item cell).
+  - Items are the canonical `ProductPresentation` contract only (identity, title, optional image with alt, canonical `Money` price, optional `compareAtPrice`/`rating`/`badge`). An unresolved price renders an unavailable state with add-to-cart disabled — never a zero. Ratings, badges and crossed-out prices render only from host-supplied data; the block invents no evidence. Prices render through the canonical `formatMoney` path (no hardcoded currency symbol) and all user-facing copy is overridable with the previous Spanish defaults.
+  - Removes the numbered exports `ProductCard1`, `ProductCard2`, `ProductCard3`, `ProductCard5`, their types `ProductCard1Product` / `ProductCard1Props`, the contracts surface `productCard1PropsSchema` / `ProductCard1SpecProps`, and the `product-card-3-reaction-toggle` / `product-card-5-reaction-toggle` / `product-card-5-checkbox-check` subcomponents.
+  - Migration: supply item data in the canonical presentation contract (canonical `Money` amounts as decimal major-unit strings plus `currencyCode`). The former numeric-price props (`price: number`, `originalPrice?: number`, mandatory demo merchandising fields) are not retained; map them to `Money` at your boundary. Consumer code importing a numbered card selects the equivalent bounded presentation (`1` → `classic`, `2` → `minimal`, `3` → `rich`); the former comparison table has no replacement in this block.
+
+- f011717: Consolidate the `home.categories` family into one canonical `ProductCategory` block.
+
+  - Adds `ProductCategory` (export + `productCategoryPropsSchema` / `ProductCategoryProps`) built on the canonical `CategoryCard` shape. It exposes a bounded `presentation` prop (`grid` | `icons` | `list`); optional per-category data (`icon` as a serializable key, `subcategories`, `featured`, `itemCount`) degrades gracefully when absent.
+  - Interaction is controlled: `onBrowse` / `onViewAll` / `onQueryChange` report from handlers with no private query state; a category count is omitted when absent or invalid and a real zero is preserved; a missing image renders a neutral placeholder, never `src=""`; no copy, currency, or demo metrics are hardcoded.
+
+  BREAKING: removes the `ProductCategory1`, `ProductCategory2`, `ProductCategory4`, and `ProductCategory5` exports (and the `product-categories/avatar-group` helper) that this canonical block supersedes. Consumers must migrate to `ProductCategory` with the `presentation` prop.
+
+- ece154d: Consolidate the `product.overview` family into one canonical `ProductOverview` block.
+
+  - Adds `ProductOverview` (export + `productOverviewPropsSchema` / `ProductOverviewProps`) built on the canonical `ProductDetailProduct` projection and canonical `Money`. It exposes a bounded `presentation` prop (`standard` | `gallery` | `rich`); `rich` accepts optional `specifications` / `features` / `reviews` props and degrades gracefully when they are absent.
+  - Selection and quantity are controlled; `onAddToCart` emits the explicitly selected backend variant id and quantity and never substitutes the first variant. Missing price renders as unavailable, never `$0`; currency is never hardcoded.
+
+  BREAKING: removes the `ProductOverview1`, `ProductOverview2`, and `ProductOverview5` exports (and the `product-overview-5-*` subcomponents) that this canonical block supersedes. Consumers must migrate to `ProductOverview` with the `presentation` prop.
+
+- b41cc50: Consolidate the numbered shopping-cart family into one canonical `ShoppingCart` block.
+
+  - Adds `ShoppingCart` (export + `shoppingCartPropsSchema` / `ShoppingCartSpecProps` in the contracts surface) with a bounded `presentation` prop (`compact` | `page`). `compact` is the former `ShoppingCart4` review card; `page` is the same contract with the page-level structure. The optional promo-entry affordance reports the entered code via `onApplyPromo(code)` and renders only authoritative promotion/discount data — it is hidden when the callback is absent, and the block never validates promotion codes itself. Host-supplied `recentlyViewed` suggestions replace the former `ShoppingCart2` recommendations, priced with canonical `Money`.
+  - Items are the canonical contract only: identity, title, quantity, optional image (omitted when absent, never `src=""`), and canonical `Money` amounts. Each line carries the backend-authoritative `lineTotal` (rendered verbatim; a malformed amount renders as unavailable — never a zero or free-shipping claim) and an optional `unitPrice` carried verbatim but never used for local arithmetic. `totals` come from the backend and are rendered verbatim; no local tax/shipping/threshold math, no fabricated merchandising, no hardcoded currency.
+  - Removes the numbered exports `ShoppingCart1`, `ShoppingCart2`, `ShoppingCart3`, `ShoppingCart4` (and their `ShoppingCart1CartItem`, `ShoppingCart2Props`/`ShoppingCart2Item`, `ShoppingCart3Props`/`ShoppingCart3CartItem`, `ShoppingCart4Props`/`ShoppingCart4Item` types), the contracts surface `shoppingCart4PropsSchema` / `ShoppingCart4SpecProps`, and the `shopping-cart-{1,2,3,4}-spinning-counter`, `shopping-cart-2-recommendations`, and `shopping-cart-2-item-row` subcomponents.
+
+  BREAKING: consumers importing a numbered cart must migrate to `ShoppingCart` with the `presentation` prop. The former numeric-price props (`price: number`, local `taxRate`/shipping-threshold arithmetic) are not retained; map item amounts to canonical `Money` (`{ amount, currencyCode }`) at your boundary and pass backend `totals` verbatim.
+
+- f011717: Consolidate the `home.hero` family into one canonical `StorefrontHero` block.
+
+  - Adds `StorefrontHero` (export + `storefrontHeroPropsSchema` / `StorefrontHeroProps` / `StorefrontHeroProduct` in the contracts surface) with a bounded `presentation` prop (`compact` | `showcase` | `editorial` | `promotional`) reusing the registry's archetype intent vocabulary. `compact` is the former `StorefrontHero1` text-forward hero with product grid and editorial image seam; `showcase` the former `StorefrontHero2` search + rotating product carousel (the search input renders only when `onSearch` is supplied); `editorial` the former `StorefrontHero5` department grid with optional featured deals and store locator; `promotional` the former `StorefrontHero6` deals bar + category grid.
+  - Truthful evidence only: ratings, review counts, category/department counts, deal descriptions, and countdowns render only from host-supplied data; discount treatments render only from a real `originalPrice > price` pair (`isOnSale` is dropped); `currency` (ISO 4217) formats all amounts via `Intl.NumberFormat` — no hardcoded `$`. Rotation respects reduced motion and is presentation-internal.
+  - The storefront catalog declares `StorefrontHero` as the single `home.hero` variant with `legacyAliases` (`StorefrontHero1`/`2`/`5`/`6` → the canonical), so existing manifests storing the numbered names keep regenerating to a working composition; `archetypes.json` intents map each intent to its matching presentation.
+
+  BREAKING: removes the `StorefrontHero1`, `StorefrontHero2`, `StorefrontHero5`, and `StorefrontHero6` exports (and the `StorefrontHero1Props` type) that this canonical block supersedes. The `FeaturedProduct` type is now exported from the canonical source and its evidence fields (`brand`, `colors`, `rating`, `reviewCount`, `originalPrice`) are optional. Consumers must migrate to `StorefrontHero` with the `presentation` prop.
+
+- dc2b11b: Split the category collection into an item cell and a listing.
+
+  - `CategoryCard` is the item cell: one `category` at a time, with the existing `grid`, `icons` and `list` presentations. It renders no section, heading, search, CTA or empty state.
+  - `CategoryGrid` is the listing: it owns the collection, `maxItems`, section copy, controlled search (list presentation), loading skeletons and the empty state, and renders `CategoryCard` for every item.
+  - BREAKING: `ProductCategory` (collection) is replaced by `CategoryGrid`; the single-item surface is `CategoryCard`. `ProductCategoryProps` is replaced by `CategoryGridProps` / `CategoryCardProps`.
+
+  Migration: replace `<ProductCategory categories={items} ... />` with `<CategoryGrid categories={items} ... />`. For a single category, render `<CategoryCard category={item} ... />`.
+
+- 3e43eb0: BREAKING: `ProductCard` is now an item cell and a new `ProductGrid` listing owns the collection.
+
+  - `ProductCard` (`packages/blocks/src/blocks/e-commerce/product-list/product-card.tsx`) now takes a single `item: ProductPresentation` (plus `presentation?` and `wishlisted?`) and renders exactly one cell — no section wrapper, no section heading, no grid, and no item cap. The `items`, `heading`, and `maxItems` props and the `wishlistedIds` collection prop are removed; `wishlisted` is now a single host-resolved boolean.
+  - The serializable contract `productCardPropsSchema` / `ProductCardSpecProps` changes accordingly (`{ item, presentation?, wishlisted? }`), still without callbacks or label strings.
+  - Adds `ProductGrid` (export + `productGridPropsSchema` / `ProductGridSpecProps`) as the canonical listing: it takes `items: ProductPresentation[]`, an optional `presentation`, `heading`, `maxItems`, `wishlistedIds`, and owns the `loading` (skeletons), `empty` (overridable copy), and ready states. It renders `ProductCard` cells (single source of cell markup) and reports actions through the same callbacks. `error` remains the host's responsibility.
+  - Migration: pass a listing's data to `ProductGrid` with `items`, `heading`, and `maxItems`; pass a single item to `ProductCard` via `item`. Resolve rich-presentation wishlist state per cell through `wishlistedIds` on the grid or `wishlisted` on the cell. The delimited showcase `ProductShowcase1` is unchanged.
+
+- b41cc50: Require an image for the `Feature` block's `split` presentation.
+
+  - `featureSplitSpecSchema` now requires `presentation: 'split'` and a non-empty, trimmed `image.src`; `featureCardsSpecSchema` keeps `image` out of its contract. `featurePropsSchema` is the union of both branches, so TypeScript narrows `image` only after checking `presentation`.
+  - The component throws a configuration error when an untyped caller renders `split` without a non-empty image, instead of silently dropping the media column. `cards` is unchanged.
+  - Editorial fallbacks belong to the consumer, not the block library. The showcase now owns `public/demo/editorial-fallback.svg`; the storefront template seeds a neutral image in user-owned `content.ts`.
+
+  Migration: pass `{ image: { src, alt } }` when using `presentation="split"`, or switch to `presentation="cards"` if the section is icon-only. Replace the storefront's neutral seed with real editorial imagery.
+
+### Minor Changes
+
+- 80d4137: Add optional, backward-compatible brand customization to existing surfaces (M5):
+
+  - `@thorprovider/blocks`: `Navbar4` and `FooterSection1` accept an optional wordmark accent `{ text, className }` (trailing segment of the brand name) and an optional surface `className`; a supplied surface `className` overrides the default surface paint (default background/backdrop not emitted) so a branded surface paints correctly. `StorefrontHero1` accepts an optional editorial `heroImage { src, alt }` rendered with a native, guarded image. `ProductCategory2` accepts an optional `itemCount`: an unknown count is omitted (no fabricated `0`), a real `0` is preserved, and non-finite/negative values render no count. All props are optional and omit to the current rendering, so existing consumers are unchanged; no new block type or variant is added, and the blocks stay framework-, backend-, and data-free.
+  - `@thorprovider/storefront`: the scaffold generates a user-owned `lib/<name>/shell/{content,props}.ts` seam (brand accents, surface classes, footer description/links, newsletter) that the derived spec composes last, so `storefront sync` regenerates only derived wiring and preserves user-owned edits. The scaffold ships no newsletter submit callback, so the newsletter is omitted by default rather than rendering a fake form; default footer copy makes no delivery/shipping promise and links only to routes the storefront serves (no assumed route). No new identity CLI command is added — `create --site-name` already covers the site name.
+
+  This changeset adds release metadata only; it does not bump versions or publish packages.
+
+- 3b3c24c: Add validated single-store commerce contracts, explicit real/mock policy, directed variant pricing, persistent guest carts, backend-authoritative totals, manual TEST checkout, and capability-authorized receipt reconciliation in generated storefronts.
+
+  Breaking migration: `@thorprovider/types` is now entirely type-only. Import `SupportedProviderType`, `PROVIDER_METADATA`, `isSupportedProviderType`, `getProviderMetadata`, and `StorefrontConfigError` from `@thorprovider/adapters` instead. The pre-1.0 curated blocks/runtime APIs also change: product detail uses canonical options/variants/Money and explicit variant selection; confirmation totals and lines use Money; `formatMoney` returns `null` for unavailable values. Real-mode failures no longer silently return mock data.
+
+  The local packed MVP candidate retains its exact current version pins until a separate release updates the compatible toolset. This changeset does not publish packages or establish public-sales readiness.
+
+- b41cc50: Deliver the global shopper account experience (M5, change `storefront-navbar-account-menu`):
+
+  - `@thorprovider/blocks`: `Navbar4` renders a session-driven account affordance from consumer props only. An authenticated `user` (optional `avatar`) with `accountMenuItems` gets an account menu (identity + configured items + consumer-supplied sign-out); no `user` with a configured `accountHref` gets a signed-out entry point on desktop and mobile; neither configured renders no account affordance or empty container. Optional `accountPending`/`accountUnavailable` drive a pending/disabled state and an accessible unavailable/retry state (`onAccountRetry`) without presenting either as anonymous, and sign-out is suppressed while pending. Absent avatar uses the initials fallback (no empty image `src`). All callbacks stay consumer bindings outside the serializable JSON prop schema; the block never authenticates.
+  - `@thorprovider/storefront`: a mounted `customer-auth` resolves the shopper server-side per request and seeds an allowlisted display identity (`id`, `email`, `firstName`, `lastName`; the auth token stays in its httpOnly cookie). One shared client lifecycle (`account-lifecycle.client.tsx`) owns identity, guarded claims, login/register/logout, and retry with no identity fetch on mount or navigation; it reconciles same-store tabs through non-secret store-scoped signals (`BroadcastChannel` with a storage-event fallback) and on foreground/resume, discards stale generations, and shows a neutral pending state instead of stale identity/orders or a fake sign-out. `/account` is the only account surface — sign-in, registration, identity, sign-out, and real paginated orders + detail (route-scoped commerce, no direct HTTP); no address book/profile/wishlist/social/recovery/cart-merge. Account wiring is delivered through derived files (`account-session*.ts`, `account-lifecycle/account-boundary/account-mutation/account-reconcile.client.*`, `account-private.core.ts`, `account-user.core.ts`, `projection-ownership*.ts`, `registry.tsx`, `schema.ts`, `spec/index.ts`); user-owned files (`views/*/{schema,content,props,data}.ts`, `mappers.ts`, `icon-map.ts`, `shell/**`) survive `sync`. `storefront feature add|remove customer-auth` toggles the `/account` route, session reads, listeners, and navbar chrome together; without the feature the generated registry carries no account-lifecycle/account-reconcile reference and reads no session.
+  - `@thorprovider/adapters`: `getCurrentCustomer()` resolves `null` only for a confirmed unauthenticated response (HTTP 401 / `"Unauthorized"`) and throws a typed `ProviderAPIError` (`GET_CURRENT_CUSTOMER_FAILED`) on operational failures (network, timeout, 5xx), so a host can distinguish an anonymous shopper from a backend outage and render the unavailable state instead of a false sign-out. `isAuthenticated()` delegates to it and can reject. Signature and framework-agnostic boundary are unchanged.
+
+  This changeset adds release metadata only; it does not bump versions or publish packages.
+
+- ece154d: Gate the `ProductOverview` wishlist affordance on a wired handler.
+
+  - `ProductOverview` renders its wishlist button only when `onToggleWishlist` is supplied; an unwired button is a dead control and is no longer rendered in any presentation (`standard`, `gallery`, `rich`).
+  - The storefront product template and the demo/electrostore registries drop their no-op `onToggleWishlist` wiring, so a storefront without wishlist backend support no longer shows a non-functional heart.
+
+### Patch Changes
+
+- ece154d: Align the `Breadcrumb` block with the page content: the trail now renders inside the shared responsive container (`mx-auto w-full max-w-7xl px-4 py-4 sm:px-6 lg:px-8`) that sibling blocks use, instead of sitting flush against the viewport edge. The container is merged with the incoming `className` via `cn`, so a custom `className` can still override it.
+- Updated dependencies [23f876f]
+- Updated dependencies [3b3c24c]
+  - @thorprovider/types@6.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-09-23"
+lastReviewed: "2026-10-17"
 ---
 
 # @thorprovider/blocks
@@ -30,7 +30,7 @@ src/
     │   └── hero-sections/hero-section-1.tsx
     └── e-commerce/
         ├── product-list/product-card-1.tsx
-        └── storefront-hero/storefront-hero-1.tsx
+        └── storefront-hero/storefront-hero.tsx
 ```
 
 Blocks follow `src/blocks/<category>/<section>/<block>.tsx`. Each block co-locates its own prop types unless a contract is shared by two or more blocks.
@@ -46,8 +46,7 @@ Blocks follow `src/blocks/<category>/<section>/<block>.tsx`. Each block co-locat
 | `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 |
-| `Feature1` | Marketing | Icon feature grid |
-| `Feature2` | Marketing | Split features with image |
+| `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 |
 | `FaqBlock1` | Marketing | FAQ accordion (single or multiple open) |
@@ -56,33 +55,22 @@ Blocks follow `src/blocks/<category>/<section>/<block>.tsx`. Each block co-locat
 | `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 |
-| `ProductCard1` | E-commerce | Deals grid of product cards with add-to-cart |
-| `ProductCard2` | E-commerce | Clean three-up grid with ratings |
-| `ProductCard3` | E-commerce | Deals grid with badges, low-stock and wishlist |
-| `ProductCard5` | E-commerce | Table-style comparison with sorting and filtering |
+| `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 |
-| `ProductOverview1` | E-commerce | Product detail with gallery, variants and add-to-cart |
+| `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 |
-| `ProductCategory1` | E-commerce | Category grid with view-all |
-| `ProductCategory2` | E-commerce | Image-based category cards |
-| `ProductCategory4` | E-commerce | Icon grid with customer/product counts |
-| `ProductCategory5` | E-commerce | Category list with search and subcategories |
+| `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 |
-| `ShoppingCart1` | E-commerce | Detailed cart summary |
-| `ShoppingCart2` | E-commerce | Cart with promo code and shipping |
-| `ShoppingCart4` | E-commerce | Cart review with backend-authoritative totals; `presentation` `compact` (collapsible card) or `page` (full-width review) |
+| `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 |
 | `CheckoutConfirmation` | E-commerce | Order confirmation with fulfilment timeline |
 | `OrderHistory1` | E-commerce | Orders list |
 | `OrderHistory2` | E-commerce | Order cards with carousel items |
-| `StorefrontHero1` | E-commerce | Storefront hero with gradient headline, CTAs and a product grid |
-| `StorefrontHero2` | E-commerce | Search field above a trending product carousel |
-| `StorefrontHero5` | E-commerce | Departments grid with featured deals |
-| `StorefrontHero6` | E-commerce | Rotating deals bar beside category cards |
+| `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 |
@@ -90,7 +78,7 @@ Blocks follow `src/blocks/<category>/<section>/<block>.tsx`. Each block co-locat
 | `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`). Elements stay in the DOM with no-op behavior when a callback is absent.
+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.
 
 ## Optional brand props
 
@@ -104,7 +92,7 @@ the block's current output unchanged; no demo content is added.
   segment of `logoText`, the wordmark renders unchanged.
 - `FooterSection1` — `brandAccent?: { text: string; className?: string }` applies
   the same trailing-segment accent to `brandName`.
-- `StorefrontHero1` — `heroImage?: { src: string; alt: string }` renders a native
+- `StorefrontHero` — `heroImage?: { src: string; alt: string }` renders a native
   `<img>` when `src` is a non-empty string, and nothing when the prop is absent
   or `src` is blank (never an empty `src`). The product grid is unaffected.
 
@@ -132,6 +120,24 @@ supplied surface. `Navbar4` 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
+
+`Navbar4` 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,
+and the consumer's sign-out action on desktop and mobile. Given no `user` but a
+configured `accountHref`, it renders a signed-out account entry point on both
+viewports; with neither configured it renders no account affordance and no empty
+container. An absent `avatar` uses the initials fallback and emits no empty image
+`src`. Optional `accountPending` and `accountUnavailable` props drive a
+pending/disabled state and an accessible unavailable/retry state (via
+`onAccountRetry`) without presenting either as an anonymous session, and sign-out
+is suppressed while pending. All callbacks (`onSignOut`, `onAccountRetry`,
+`onHelp`) are consumer bindings kept outside the serializable JSON prop schema;
+the sign-out action is supplied by the consumer, so the block never performs
+authentication.
+
 ## Footer newsletter
 
 `FooterSection1` renders the interactive newsletter form (input + submit button)
@@ -144,15 +150,16 @@ paints white-on-light. No magic colors are introduced by the block.
 The cart is presented in two shapes that share one data contract, so a change in
 either is visible in the other.
 
-- `ShoppingCart4` is the cart block. Its optional `presentation` prop selects
+- `ShoppingCart` is the cart block. Its optional `presentation` prop selects
   `'compact'` (default: a collapsible `max-w-md` card with an internal scroller —
   the navbar lateral) or `'page'` (always expanded, full-width `max-w-3xl`, no
   collapse control, ordinary page scrolling — the `/cart` review route).
   Omitting `presentation` renders the compact card byte-identically to before.
-- Line amounts prefer the canonical `lineTotal?: Money` and fall back to the
-  legacy numeric `price * quantity` only when `lineTotal` is absent. A missing or
-  malformed `Money` renders the `amountUnavailableLabel` (never a fabricated
-  zero or a currency fallback). `unitPrice?: Money` is carried verbatim.
+- Line amounts render the authoritative `lineTotal: Money` verbatim (backend
+  line total, never a local `unitPrice × quantity` computation); a malformed
+  amount renders the `amountUnavailableLabel` (never a fabricated zero or a
+  currency fallback). An optional `unitPrice: Money` is carried verbatim but
+  never used for any local arithmetic.
 - `totalsState` (`'idle' | 'pending' | 'error'`) plus `onRetryTotals` make the
   totals controlled: pending retains the last confirmed totals and disables
   conflicting mutations; error shows the error label and a retry.
@@ -160,6 +167,13 @@ either is visible in the other.
   by backend line id) and `onRemove(id)` removes by the same id.
   `checkoutUnavailable` hides the checkout action (e.g. no checkout installed)
   and `checkoutDisabled` disables it (e.g. pending or invalid totals).
+- Promo entry is an optional affordance: with `onApplyPromo(code)` it renders an
+  input that reports the entered code and shows only the authoritative applied
+  promotion/discount already present in `totals`; without the callback it is not
+  rendered, and the block never validates or resolves a code itself.
+  `onApplyPromo` never gates `recentlyViewed`, an optional host-supplied
+  suggestion list (name, optional image, optional `Money` price) rendered only
+  when supplied.
 
 `Navbar4` owns the lateral. Pass `cartOpen` + `onCartOpenChange` to control the
 sheet's visibility from host state (omit both to keep the legacy uncontrolled
@@ -170,6 +184,32 @@ canonical `lineTotal` (never the placeholder numeric price), plus
 serve, and a `state` (`'idle' | 'pending' | 'error'`) with retry for read/mutation
 feedback.
 
+## Product card (canonical)
+
+`ProductCard` is the item cell of a product listing and the canonical member of
+the product-card family. Its items are `ProductPresentation` only (canonical
+`Money`): a missing price renders the `unavailablePriceLabel` with add-to-cart
+disabled — never a zero amount — and optional image, rating, badge, and
+compare-at price are omitted when absent (no empty `src`, no empty stars, no
+empty chip). A compare-at price renders only when it is valid and strictly
+higher than the selling price.
+
+The bounded `presentation` option selects the structure — `classic` (boxed card
+with an add-to-cart footer), `minimal` (lean image-forward tile with an
+icon-only cart action), `rich` (overlay actions: wishlist heart and
+view-similar) — while the data and action contract stays identical. Ratings,
+badges, and scarcity copy render only from host-supplied data (the `badge`
+copy and `compareAtPrice` are the evidence channels); the block never invents
+stars, chips, or urgency.
+
+The wishlist heart is host-owned: pass `wishlistedIds` to control it, and
+`onToggleWishlist(item, nextState)` receives every toggle from the click
+handler (never from an effect). Without host state the heart keeps an
+uncontrolled visual fallback and still reports. `onViewSimilar` renders its
+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.
@@ -229,11 +269,11 @@ unique by contract, not by convention. See
 rules and the review checklist.
 
 Optional numeric projections are omitted rather than fabricated: e.g.
-`ProductCategory2Category.itemCount` renders a count only when it is a supplied
+`ProductCategoryItem.itemCount` renders a count only when it is a supplied
 finite non-negative number (a real `0` is preserved); an unknown count renders
 no count text, never a fabricated `0`.
 
-Product presentations (`ProductCard1`, `ProductShowcase1`) accept either the
+Product presentations (`ProductGrid`, `ProductShowcase1`) accept either the
 legacy numeric-price props or a canonical `ProductPresentation` (`price`/
 `compareAtPrice` as `Money`, `{ amount: string, currencyCode: string }` in
 decimal major units). The canonical path formats with the store currency and
@@ -242,6 +282,10 @@ locale, renders a truthful "unavailable" state for an unresolved price (never
 valid and strictly higher. Optional rating/badge/image appear only when
 supplied; a missing image is omitted, never `src=""`.
 
+The canonical `ProductCard` accepts only the canonical `ProductPresentation`
+contract — the legacy numeric-price props of the numbered cards are retired
+(migrate item data to canonical `Money`).
+
 ## Block interaction contracts
 
 State and events between a block, its host registry, and the store must follow

package/docs/standards/data-contracts.md

@@ -1,7 +1,7 @@
 ---
 title: "Block data contracts"
 purpose: "Warn block authors and hosts about the two boundary data-hygiene rules that prevent empty-src and duplicate-key console errors"
-lastReviewed: "2026-09-27"
+lastReviewed: "2026-10-17"
 type: standards
 tags: [blocks, contracts, data-boundary, images, react-keys]
 ---
@@ -60,6 +60,16 @@ Even with correct boundaries, blocks should render
 `src={value || undefined}` for every image prop. This is a cheap invariant
 that makes the whole catalog immune to one misbehaving host.
 
+## Canonical product card: evidence comes from the host
+
+`ProductCard` renders ratings, badges, discount labels, and stock claims only
+from host-supplied data (`rating`, `badge` copy, `compareAtPrice`); it never
+invents stars, chips, scarcity copy, or crossed-out prices, and a compare-at
+price renders only when it is valid and strictly higher. Boundaries must not
+compensate by fabricating evidence: if the host lacks a rating, the card
+renders none — do not serialize a default `5` or a stock-urgency string to
+"fill" the UI.
+
 ## Review checklist (boundary code)
 
 - [ ] No `?? ''` or `|| ''` on visual fields (image, avatar, icon) in mappers/transforms.
@@ -67,4 +77,5 @@ that makes the whole catalog immune to one misbehaving host.
 - [ ] Optional fields emit `undefined`, never `""`.
 - [ ] Arrays passed as React children have unique keys guaranteed by contract or deduped at the boundary.
 - [ ] Concatenated arrays (categories + links) are deduped before render.
-- [ ] Every `<img>`/`<AvatarImage>` in the block uses `src={expr || undefined}`.
+- [ ] Every `<img>`/`<AvatarImage>` in the block uses `src={expr || undefined}`.
+- [ ] No fabricated ratings, badges, stock claims, or crossed-out prices are serialized to fill absent evidence.

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@thorprovider/blocks",
-  "version": "0.1.3",
+  "version": "1.0.0",
   "description": "Reusable, framework-agnostic React component blocks for Thor Commerce storefronts.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "sideEffects": [
+    "**/*.css",
+    "./styles.css"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -13,16 +17,23 @@
       "default": "./dist/index.mjs"
     },
     "./contracts": {
-      "types": "./dist/contracts.d.ts",
-      "development": "./dist/contracts.mjs",
-      "import": "./dist/contracts.mjs",
-      "require": "./dist/contracts.js",
-      "default": "./dist/contracts.mjs"
+      "types": "./dist/lib/contracts.d.ts",
+      "development": "./dist/lib/contracts.mjs",
+      "import": "./dist/lib/contracts.mjs",
+      "require": "./dist/lib/contracts.js",
+      "default": "./dist/lib/contracts.mjs"
     },
-    "./styles.css": "./styles.css"
+    "./styles.css": "./styles.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "development": "./dist/*.mjs",
+      "import": "./dist/*.mjs",
+      "require": "./dist/*.js",
+      "default": "./dist/*.mjs"
+    }
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc -p tsconfig.build.json && node scripts/fix-esm-extensions.mjs",
     "dev": "tsup --watch",
     "type-check": "tsc --noEmit",
     "test": "vitest run --config vitest.config.ts",
@@ -40,7 +51,7 @@
   "license": "MIT",
   "dependencies": {
     "@base-ui/react": "^1.8.0",
-    "@thorprovider/types": "^5.8.0",
+    "@thorprovider/types": "workspace:^",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cn": "^0.4.0",
@@ -54,10 +65,15 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
+    "@testing-library/dom": "^10",
+    "@testing-library/react": "^16",
+    "@testing-library/user-event": "^14",
+    "@types/jsdom": "^30",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "jsdom": "^30.1.3",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.2.4"
   }
-}
+}

package/scripts/fix-esm-extensions.mjs

@@ -0,0 +1,40 @@
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join, extname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const distDir = fileURLToPath(new URL("../dist/", import.meta.url));
+
+const RELATIVE = /^\.{1,2}\//;
+const HAS_EXT = /\.(mjs|cjs|js|jsx|ts|tsx|css|json|svg|png|webp|jpg|jpeg|gif|woff2?)$/;
+
+const SPECIFIER =
+  /(\bfrom\s*|\bimport\s*\(|\brequire\s*\(|\bimport\s+)(["'])(\.{1,2}\/[^"']*?)\2/g;
+
+async function* walk(dir) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) yield* walk(full);
+    else yield full;
+  }
+}
+
+async function fixFile(file) {
+  const ext = extname(file);
+  if (ext !== ".mjs" && ext !== ".js") return 0;
+  const target = ext === ".mjs" ? ".mjs" : ".js";
+  const source = await readFile(file, "utf8");
+  let changed = 0;
+  const out = source.replace(SPECIFIER, (match, prefix, quote, spec) => {
+    if (!RELATIVE.test(spec) || HAS_EXT.test(spec)) return match;
+    changed += 1;
+    return `${prefix}${quote}${spec}${target}${quote}`;
+  });
+  if (changed > 0) await writeFile(file, out);
+  return changed;
+}
+
+let total = 0;
+for await (const file of walk(distDir)) {
+  total += await fixFile(file);
+}
+console.log(`fix-esm-extensions: rewrote ${total} relative specifier(s)`);

package/src/blocks/e-commerce/product-categories/category-card-grid.test.tsx

@@ -0,0 +1,122 @@
+// @vitest-environment jsdom
+import { renderToStaticMarkup } from 'react-dom/server'
+import { beforeAll, describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { CategoryCard } from './category-card'
+import { CategoryGrid } from './product-category-grid'
+import type { ProductCategoryItem } from '../../../lib/contracts'
+
+beforeAll(() => {
+  ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+})
+
+const category: ProductCategoryItem = {
+  id: 'pcat_herramientas',
+  handle: 'herramientas',
+  name: 'Herramientas',
+  description: 'Taladros y accesorios',
+  image: '/products/drill.png',
+  itemCount: 12,
+  trending: true,
+  featured: true,
+  subcategories: ['Taladros', 'Accesorios'],
+}
+
+const categories: ProductCategoryItem[] = [
+  category,
+  { ...category, id: 'pcat_pintura', handle: 'pintura', name: 'Pintura', image: undefined },
+  { ...category, id: 'pcat_jardin', handle: 'jardin', name: 'Jardín' },
+]
+
+const card = (extra: Record<string, unknown> = {}) =>
+  renderToStaticMarkup(<CategoryCard category={category} {...extra} />)
+
+const grid = (extra: Record<string, unknown> = {}) =>
+  renderToStaticMarkup(<CategoryGrid categories={categories} {...extra} />)
+
+describe('CategoryCard — item cell', () => {
+  it('renders a single category without section chrome', () => {
+    const html = card()
+    expect(html).toContain('Herramientas')
+    expect(html).not.toContain('<section')
+    expect(html).not.toContain('<h2')
+  })
+
+  it('renders the image for the grid presentation and omits it for icons', () => {
+    expect(card()).toContain('/products/drill.png')
+    expect(card({ presentation: 'icons' })).not.toContain('<img')
+  })
+
+  it('keeps counts honest (zero and unknown are not invented)', () => {
+    expect(card()).toContain('12')
+    expect(renderToStaticMarkup(<CategoryCard category={{ ...category, itemCount: undefined }} />)).not.toContain('items</span>')
+    expect(renderToStaticMarkup(<CategoryCard category={{ ...category, itemCount: 0 }} />)).not.toContain('items</span>')
+  })
+
+  it('only exposes browse when a handler exists', () => {
+    expect(card({ browseLabel: 'Ver' })).not.toContain('Ver Herramientas')
+    const html = card({ browseLabel: 'Ver', onBrowse: vi.fn() })
+    expect(html).toContain('aria-label="Ver Herramientas"')
+  })
+
+  it('renders the list cell with description, chips and featured badge', () => {
+    const html = card({ presentation: 'list', featuredLabel: 'Destacada', itemsLabel: 'productos' })
+    expect(html).toContain('Taladros y accesorios')
+    expect(html).toContain('Taladros')
+    expect(html).toContain('Destacada')
+    expect(html).toContain('productos')
+  })
+})
+
+describe('CategoryGrid — listing', () => {
+  it('renders one cell per category', () => {
+    const html = grid()
+    expect(html).toContain('Herramientas')
+    expect(html).toContain('Pintura')
+    expect(html).toContain('Jardín')
+    expect(html.match(/data-slot="card"/g) ?? []).toHaveLength(3)
+  })
+
+  it('caps the rendered collection with maxItems', () => {
+    const html = grid({ maxItems: 2 })
+    expect(html).toContain('Herramientas')
+    expect(html).toContain('Pintura')
+    expect(html).not.toContain('Jardín')
+  })
+
+  it('owns its loading state with skeletons and no cells', () => {
+    const html = grid({ loading: true, skeletonCount: 3 })
+    expect(html).toContain('aria-busy="true"')
+    expect(html).not.toContain('data-slot="card"')
+  })
+
+  it('owns its empty state', () => {
+    expect(renderToStaticMarkup(<CategoryGrid categories={[]} emptyLabel="Sin categorías" />)).toContain('Sin categorías')
+  })
+
+  it('renders the search control only in the list presentation', () => {
+    expect(grid({ presentation: 'grid', onQueryChange: vi.fn() })).not.toContain('type="search"')
+    expect(grid({ presentation: 'list', onQueryChange: vi.fn(), searchPlaceholder: 'Buscar' })).toContain('type="search"')
+  })
+
+  it('renders view-all only outside the grid and the section cta only outside the list', () => {
+    const withBoth = { cta: { label: 'Comprar', href: '/tienda' }, onViewAll: vi.fn(), viewAllLabel: 'Ver todo' }
+    const gridHtml = grid({ presentation: 'grid', ...withBoth })
+    expect(gridHtml).toContain('Comprar')
+    expect(gridHtml).not.toContain('Ver todo')
+    const listHtml = grid({ presentation: 'list', ...withBoth })
+    expect(listHtml).toContain('Ver todo')
+    expect(listHtml).not.toContain('Comprar')
+  })
+
+  it('forwards the controlled query to the search input', async () => {
+    const user = userEvent.setup()
+    const onQueryChange = vi.fn()
+    render(<CategoryGrid categories={categories} presentation="list" query="tal" onQueryChange={onQueryChange} searchLabel="Buscar categorías" />)
+    const input = screen.getByLabelText('Buscar categorías') as HTMLInputElement
+    expect(input.value).toBe('tal')
+    await user.type(input, 'a')
+    expect(onQueryChange).toHaveBeenCalled()
+  })
+})