@thorprovider/blocks 0.1.1 → 0.1.3

package/src/blocks/marketing/navbars/navbar-4.tsx

@@ -2,19 +2,20 @@
 
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { AnimatePresence, motion, useReducedMotion } from 'motion/react'
-import { Menu, Search, ShoppingBag, X } from 'lucide-react'
+import { Menu, Search, ShoppingBag, UserRound, RotateCcw, X } from 'lucide-react'
 
 import { Button } from '../../../ui/button'
 import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger } from '../../../ui/sheet'
 import { cn } from '../../../lib/utils'
 
 import { Navbar4AccountMenu, type AccountMenuItem, type StoreUser } from './navbar-4-account-menu'
-import { Navbar4CartSheet, type CartItem } from './navbar-4-cart-sheet'
+import { Navbar4CartSheet, type CartItem, type CartSheetState } from './navbar-4-cart-sheet'
 import type { UtilityLink } from './navbar-4-mobile-nav'
 import { Navbar4SearchBar } from './navbar-4-search-bar'
 import { MegaMenu } from '../../e-commerce/navigation/mega-menu'
 import { MobileCategoryDrawer } from '../../e-commerce/navigation/mobile-category-drawer'
 import type { MenuItem } from '../../../lib/types/menu'
+import type { Money } from '@thorprovider/types'
 import type { StoreCategory } from '../../../lib/contracts'
 
 function toMenuItem(category: StoreCategory): MenuItem {
@@ -41,10 +42,21 @@ function uniqueById<T extends { id: string }>(items: T[]): T[] {
   })
 }
 
-function Logo({ text, href }: { text: string; href?: string }) {
+export interface LogoAccent {
+  /** Trailing segment of `logoText` to render with the accent styling. */
+  text: string
+  /** Consumer-supplied classes for the accent span (e.g. a brand color token). */
+  className?: string
+}
+
+function Logo({ text, href, accent }: { text: string; href?: string; accent?: LogoAccent }) {
   const className =
     'focus-visible:ring-ring flex items-center gap-2 rounded-sm focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none'
 
+  const accentText = accent?.text ?? ''
+  const hasAccent = accentText.length > 0 && text.endsWith(accentText)
+  const baseText = hasAccent ? text.slice(0, text.length - accentText.length) : text
+
   const content = (
     <>
       <svg viewBox='0 0 32 32' aria-hidden='true' className='text-primary size-7' fill='none' xmlns='http://www.w3.org/2000/svg'>
@@ -73,7 +85,10 @@ function Logo({ text, href }: { text: string; href?: string }) {
         <circle cx='13.1' cy='26.1' r='1.7' stroke='currentColor' strokeWidth='1.2' />
         <circle cx='22.1' cy='26.1' r='1.7' stroke='currentColor' strokeWidth='1.2' />
       </svg>
-      <span className='text-base font-semibold tracking-tight'>{text}</span>
+      <span className='text-base font-semibold tracking-tight'>
+        {baseText}
+        {hasAccent ? <span className={accent?.className}>{accentText}</span> : null}
+      </span>
     </>
   )
 
@@ -148,43 +163,138 @@ function CartBadge({ count }: CartBadgeProps) {
 
 export interface Navbar4Props {
   storeCategories: StoreCategory[]
-  shippingNote: string
+  /**
+   * Optional note shown in the desktop utility strip. When omitted (or empty)
+   * and there are no `utilityLinks`, the strip is not rendered at all, so a
+   * block with no optional content paints no empty decorative chrome.
+   */
+  shippingNote?: string
   utilityLinks: UtilityLink[]
   logoText: string
   logoHref?: string
-  /** When provided, a mobile-only "Account" link is appended to the utility links. */
+  /**
+   * Optional accent for a trailing segment of `logoText` (e.g. the "Cuba" in
+   * "ElectroCuba"). When omitted, or when `text` is not a trailing segment of
+   * `logoText`, the wordmark renders unchanged.
+   */
+  logoAccent?: LogoAccent
+  /** Account destination for anonymous shoppers on every viewport. */
   accountHref?: string
+  /**
+   * When `false`, no search control is rendered at all — neither the desktop
+   * input, the mobile trigger, nor the mobile panel. Defaults to `true` so
+   * legacy consumers keep the existing self-contained search. The generated
+   * storefront passes `false` while no verified global search contract exists
+   * (E2 task 5.4), so no global search is presented as working.
+   */
+  /**
+   * The storefront's current route path. When it matches a destination the link
+   * is marked as the current page (accessibly, beyond color alone).
+   */
+  currentPath?: string
+  showSearch?: boolean
   searchQuery?: string
   onSearchChange?: (value: string) => void
   items?: CartItem[]
+  /**
+   * Quantity DELTA for a backend cart line-item id. The boundary converts the
+   * delta into an absolute quantity against the authoritative current line
+   * quantity before mutating the cart.
+   */
   onQtyChange?: (id: string, delta: number) => void
+  /** Remove the backend cart line-item id. */
   onRemove?: (id: string) => void
+  /** Authoritative backend subtotal for the mini-cart. */
+  subtotal?: Money
+  /** Shown when an authoritative subtotal is supplied but absent/malformed. */
+  subtotalUnavailableLabel?: string
+  /** Override money formatting (locale, currency). Defaults to `Money.currencyCode`. */
+  formatMoney?: (money: Money) => string
   user?: StoreUser
   accountMenuItems?: AccountMenuItem[]
   onHelp?: () => void
   onSignOut?: () => void
+  accountPending?: boolean
+  accountUnavailable?: boolean
+  onAccountRetry?: () => void
   onCheckout?: () => void
   onViewCart?: () => void
+  /**
+   * Controlled visibility for the cart sheet. When provided, the sheet opens
+   * and closes from this value and `onCartOpenChange` instead of internal
+   * state, so a host can share one cart surface across the navbar trigger and
+   * successful add-to-cart. Omit both to keep the legacy uncontrolled sheet.
+   */
+  cartOpen?: boolean
+  /** Change handler paired with `cartOpen` for a controlled sheet. */
+  onCartOpenChange?: (open: boolean) => void
+  /**
+   * Backend-authoritative cart rendering for the sheet. When `true`, line
+   * amounts use each item's canonical `lineTotal` Money and never fall back to
+   * numeric `price * qty`. Omit for the legacy numeric rendering.
+   */
+  canonicalCart?: boolean
+  /** Cart read/mutation lifecycle for the sheet. */
+  cartState?: CartSheetState
+  /** Message shown when `cartState` is `error`. */
+  cartErrorLabel?: string
+  /** Recovery action label for the error state. */
+  cartRetryLabel?: string
+  /** Recovery action invoked from the error state. */
+  onCartRetry?: () => void
+  /** When `true`, the sheet's checkout action is suppressed (checkout not installed). */
+  checkoutUnavailable?: boolean
+  /** When `true`, the sheet's checkout action is disabled (cart not ready). */
+  checkoutDisabled?: boolean
+  /** When `true`, the sheet's review action is suppressed (cart view not installed). */
+  viewCartUnavailable?: boolean
+  /**
+   * Consumer-supplied classes merged onto the outer `<header>` as the final
+   * argument, so a semantic surface such as `bg-brand-nav
+   * text-brand-nav-foreground` overrides the default `bg-background`. Purely
+   * presentational: no layout, structure, or behavior changes.
+   */
+  className?: string
 }
 
 export function Navbar4({
   storeCategories,
-  shippingNote,
+  shippingNote = '',
   utilityLinks,
   logoText,
   logoHref,
+  logoAccent,
   accountHref,
+  currentPath,
+  showSearch = true,
   searchQuery: searchQueryProp,
   onSearchChange,
   items: itemsProp,
   onQtyChange: onQtyChangeProp,
   onRemove: onRemoveProp,
+  subtotal,
+  subtotalUnavailableLabel,
+  formatMoney,
   user,
   accountMenuItems,
   onHelp,
   onSignOut,
+  accountPending = false,
+  accountUnavailable = false,
+  onAccountRetry,
   onCheckout,
   onViewCart,
+  cartOpen,
+  onCartOpenChange,
+  canonicalCart,
+  cartState,
+  cartErrorLabel,
+  cartRetryLabel,
+  onCartRetry,
+  checkoutUnavailable,
+  checkoutDisabled,
+  viewCartUnavailable,
+  className,
 }: Navbar4Props) {
   /**
    * Integration seam
@@ -228,37 +338,58 @@ export function Navbar4({
   const count = useMemo(() => items.reduce((total, item) => total + item.qty, 0), [items])
 
   useEffect(() => {
-    if (!searchOpen) {
+    if (!showSearch || !searchOpen) {
       return
     }
 
     document.getElementById('store-search-mobile')?.focus()
-  }, [searchOpen])
+  }, [searchOpen, showSearch])
 
   const dismissSearch = () => {
     setSearchOpen(false)
     searchTriggerRef.current?.focus()
   }
 
+  // When the consumer overrides the header surface via `className`, the nav
+  // links inherit its text color and need an explicit hover foreground so
+  // `hover:bg-muted` never paints white-on-light; otherwise they keep the
+  // default foreground (and the default hover surface).
+  const navLinkColor =
+    className !== undefined ? 'text-inherit hover:text-foreground' : 'text-foreground'
+  // The current page is marked beyond color: an accessible current state plus a
+  // visible weight/underline, and nothing when no destination matches.
+  const isCurrent = (href?: string) => href !== undefined && href === currentPath
+
+  // The desktop utility strip is decorative chrome: it is painted only when it
+  // has content (a non-empty note or at least one utility link), never empty.
+  const hasUtilityContent = shippingNote.trim().length > 0 || utilityLinks.length > 0
+
   return (
-    <header className='border-border bg-background/95 sticky top-0 z-40 w-full border-b backdrop-blur-md supports-backdrop-filter:bg-background/80'>
-      <div className='bg-foreground text-background hidden lg:block'>
-        <div className='mx-auto flex h-9 w-full max-w-7xl items-center justify-between px-4 text-xs tracking-wide sm:px-6 lg:px-8'>
-          <p className='text-background/80'>{shippingNote}</p>
-          <ul className='flex items-center gap-5'>
-            {utilityLinks.map(link => (
-              <li key={`${link.href}:${link.label}`}>
-                <a
-                  href={link.href}
-                  className='text-background/80 hover:text-background transition-colors duration-150'
-                >
-                  {link.label}
-                </a>
-              </li>
-            ))}
-          </ul>
+    <header
+      className={cn(
+        'border-border sticky top-0 z-40 w-full border-b backdrop-blur-md',
+        className ?? 'bg-background/95 supports-backdrop-filter:bg-background/80',
+      )}
+    >
+      {hasUtilityContent ? (
+        <div className='bg-foreground text-background hidden lg:block'>
+          <div className='mx-auto flex h-9 w-full max-w-7xl items-center justify-between px-4 text-xs tracking-wide sm:px-6 lg:px-8'>
+            <p className='text-background/80'>{shippingNote}</p>
+            <ul className='flex items-center gap-5'>
+              {utilityLinks.map(link => (
+                <li key={`${link.href}:${link.label}`}>
+                  <a
+                    href={link.href}
+                    className='text-background/80 hover:text-background transition-colors duration-150'
+                  >
+                    {link.label}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </div>
         </div>
-      </div>
+      ) : null}
 
       <div className='mx-auto flex h-16 w-full max-w-7xl items-center gap-3 px-4 sm:px-6 lg:px-8'>
         <Button
@@ -285,7 +416,7 @@ export function Navbar4({
         />
 
         <div className='flex-1 lg:flex-none'>
-          <Logo text={logoText} href={logoHref} />
+          <Logo text={logoText} href={logoHref} accent={logoAccent} />
         </div>
 
         <nav aria-label='Store' className='hidden flex-1 lg:block'>
@@ -295,9 +426,11 @@ export function Navbar4({
                 <li key={category.href} className='group relative'>
                   <a
                     href={category.href}
+                    aria-current={isCurrent(category.href) ? 'page' : undefined}
                     className={cn(
                       'hover:bg-muted focus-visible:ring-ring rounded-md px-3 py-2 text-sm font-medium transition-colors duration-150 focus-visible:ring-2 focus-visible:outline-none',
-                      category.emphasis ? 'text-destructive' : 'text-foreground',
+                      category.emphasis ? 'text-destructive' : navLinkColor,
+                      isCurrent(category.href) && 'font-semibold underline underline-offset-4',
                     )}
                   >
                     {category.label}
@@ -315,9 +448,11 @@ export function Navbar4({
                 <li key={category.href}>
                   <a
                     href={category.href}
+                    aria-current={isCurrent(category.href) ? 'page' : undefined}
                     className={cn(
                       'hover:bg-muted focus-visible:ring-ring rounded-md px-3 py-2 text-sm font-medium transition-colors duration-150 focus-visible:ring-2 focus-visible:outline-none',
-                      category.emphasis ? 'text-destructive' : 'text-foreground',
+                      category.emphasis ? 'text-destructive' : navLinkColor,
+                      isCurrent(category.href) && 'font-semibold underline underline-offset-4',
                     )}
                   >
                     {category.label}
@@ -329,38 +464,67 @@ export function Navbar4({
         </nav>
 
         <div className='flex items-center gap-1.5'>
-          <div className='hidden lg:block lg:w-64'>
-            <Navbar4SearchBar
-              id='store-search'
-              value={searchQuery}
-              onValueChange={setSearchQuery}
-            />
-          </div>
+          {showSearch ? (
+            <>
+              <div className='hidden lg:block lg:w-64'>
+                <Navbar4SearchBar
+                  id='store-search'
+                  value={searchQuery}
+                  onValueChange={setSearchQuery}
+                />
+              </div>
 
-          <Button
-            ref={searchTriggerRef}
-            variant='ghost'
-            size='icon'
-            className='lg:hidden'
-            aria-label='Search products'
-            aria-expanded={searchOpen}
-            onClick={() => setSearchOpen(open => !open)}
-          >
-            {searchOpen ? <X /> : <Search />}
-          </Button>
-
-          {user ? (
-            <div className='hidden lg:block'>
-              <Navbar4AccountMenu
-                user={user}
-                items={accountMenuItems}
-                onHelp={onHelp}
-                onSignOut={onSignOut}
-              />
-            </div>
+              <Button
+                ref={searchTriggerRef}
+                variant='ghost'
+                size='icon'
+                className='lg:hidden'
+                aria-label='Search products'
+                aria-expanded={searchOpen}
+                onClick={() => setSearchOpen(open => !open)}
+              >
+                {searchOpen ? <X /> : <Search />}
+              </Button>
+            </>
           ) : null}
 
-          <Sheet>
+          {accountUnavailable ? (
+            <Button
+              variant='ghost'
+              size='icon'
+              className='size-11'
+              disabled={accountPending || !onAccountRetry}
+              aria-label='Retry account session'
+              title='Account session unavailable'
+              onClick={onAccountRetry}
+            >
+              <RotateCcw aria-hidden='true' />
+            </Button>
+          ) : user ? (
+            <Navbar4AccountMenu
+              user={user}
+              items={accountMenuItems}
+              onHelp={onHelp}
+              onSignOut={onSignOut}
+              pending={accountPending}
+            />
+          ) : accountHref ? (
+            accountPending ? (
+              <Button variant='ghost' size='icon' className='size-11' disabled aria-label='Loading account session'>
+                <UserRound aria-hidden='true' />
+              </Button>
+            ) : (
+              <Button variant='ghost' size='icon' className='size-11' asChild>
+                <a href={accountHref} aria-label='Account' aria-current={isCurrent(accountHref) ? 'page' : undefined}>
+                  <UserRound aria-hidden='true' />
+                </a>
+              </Button>
+            )
+          ) : null}
+
+          <Sheet
+            {...(cartOpen !== undefined ? { open: cartOpen, onOpenChange: onCartOpenChange } : {})}
+          >
             <SheetTrigger asChild>
               <Button
                 variant='ghost'
@@ -382,8 +546,19 @@ export function Navbar4({
                 items={items}
                 onQtyChange={changeQty}
                 onRemove={removeItem}
+                subtotal={subtotal}
+                subtotalUnavailableLabel={subtotalUnavailableLabel}
+                formatMoney={formatMoney}
                 onCheckout={onCheckout}
                 onViewCart={onViewCart}
+                canonical={canonicalCart}
+                state={cartState}
+                errorLabel={cartErrorLabel}
+                retryLabel={cartRetryLabel}
+                onRetry={onCartRetry}
+                checkoutUnavailable={checkoutUnavailable}
+                checkoutDisabled={checkoutDisabled}
+                viewCartUnavailable={viewCartUnavailable}
               />
             </SheetContent>
           </Sheet>
@@ -394,7 +569,7 @@ export function Navbar4({
         {`Cart contains ${count} ${count === 1 ? 'item' : 'items'}`}
       </p>
 
-      {searchOpen ? (
+      {showSearch && searchOpen ? (
         <div className='border-border flex flex-col gap-0 border-t p-4 lg:hidden'>
           <Navbar4SearchBar
             id='store-search-mobile'
@@ -408,4 +583,4 @@ export function Navbar4({
   )
 }
 
-export default Navbar4
+export default Navbar4

package/src/index.ts

@@ -1,3 +1,5 @@
+'use client'
+
 export { cn } from './lib/utils'
 export type { CTA } from './lib/types'
 
@@ -54,7 +56,19 @@ export { default as ProductCard1 } from './blocks/e-commerce/product-list/produc
 export { default as ProductCard2 } from './blocks/e-commerce/product-list/product-card-2'
 export { default as ProductCard3 } from './blocks/e-commerce/product-list/product-card-3'
 export { default as ProductCard5 } from './blocks/e-commerce/product-list/product-card-5'
+export { default as ProductShowcase1 } from './blocks/e-commerce/product-list/product-showcase-1'
+export type {
+  ProductCard1Product,
+  ProductCard1Props,
+} from './blocks/e-commerce/product-list/product-card-1'
+export type { ProductShowcase1Props } from './blocks/e-commerce/product-list/product-showcase-1'
 export { default as ProductOverview1 } from './blocks/e-commerce/product-overview/product-overview-1'
+export type {
+  ProductOverview1Props,
+  ProductOverview1Rating,
+  ProductDetailProduct,
+  ProductDetailVariant,
+} from './blocks/e-commerce/product-overview/product-overview-1'
 export { default as ProductOverview2 } from './blocks/e-commerce/product-overview/product-overview-2'
 export { default as ProductOverview5 } from './blocks/e-commerce/product-overview/product-overview-5'
 export type { ProductOverview2Props, ProductOverview2Product } from './blocks/e-commerce/product-overview/product-overview-2'
@@ -79,18 +93,38 @@ export { MobileCategoryDrawer, mobileCategoryDrawerPropsSchema } from './blocks/
 export type { MobileCategoryDrawerProps } from './blocks/e-commerce/navigation/mobile-category-drawer'
 export { CategoryIcon, categoryIconNameSchema, categoryIconPropsSchema } from './blocks/e-commerce/navigation/category-icon'
 export type { CategoryIconName, CategoryIconProps } from './blocks/e-commerce/navigation/category-icon'
+export { Breadcrumb, breadcrumbItemSchema, breadcrumbPropsSchema } from './blocks/e-commerce/navigation/breadcrumb'
+export type { BreadcrumbItemData, BreadcrumbProps } from './blocks/e-commerce/navigation/breadcrumb'
+export { SkipToContent, skipToContentPropsSchema } from './blocks/e-commerce/navigation/skip-to-content'
+export type { SkipToContentProps } from './blocks/e-commerce/navigation/skip-to-content'
+export { BackToTop, backToTopPropsSchema, resolveScrollBehavior } from './blocks/e-commerce/navigation/back-to-top'
+export type { BackToTopProps } from './blocks/e-commerce/navigation/back-to-top'
+export { MobileBottomNav, mobileBottomNavItemSchema, mobileBottomNavPropsSchema } from './blocks/e-commerce/navigation/mobile-bottom-nav'
+export type { MobileBottomNavItem, MobileBottomNavProps } from './blocks/e-commerce/navigation/mobile-bottom-nav'
 export { menuItemSchema, collectionItemSchema } from './lib/types/menu'
 export type { MenuItem, CollectionItem } from './lib/types/menu'
 export { default as CategoryFilter1 } from './blocks/e-commerce/category-filters/category-filter-1'
+export type {
+  CategoryFilter1Category,
+  CategoryFilter1PriceRange,
+  CategoryFilter1SortOption,
+} from './blocks/e-commerce/category-filters/category-filter-1'
 export { default as CategoryFilter2 } from './blocks/e-commerce/category-filters/category-filter-2'
+export { CategoryFilter2StatusView } from './blocks/e-commerce/category-filters/category-filter-2'
 export type {
   FilterProduct,
   CategoryFilter2Props,
   CategoryFilter2Category,
+  CategoryFilter2Collection,
   CategoryFilter2Color,
   CategoryFilter2PriceRange,
   CategoryFilter2SortOption,
   CategoryFilter2Filters,
+  CategoryFilter2Status,
+  CategoryFilter2StatusViewProps,
+  CategoryFilter2QueryError,
+  CategoryFilter2ActiveFilter,
+  CategoryFilter2ActiveFilterKind,
 } from './blocks/e-commerce/category-filters/category-filter-2'
 export { default as CategoryFilter4 } from './blocks/e-commerce/category-filters/category-filter-4'
 export type { CategoryFilter4Props, CategoryFilter4Product, CategoryFilter4Facets } from './blocks/e-commerce/category-filters/category-filter-4'
@@ -116,6 +150,9 @@ export type {
   CheckoutForm1OrderSummary,
   CheckoutForm1OrderSummaryItem,
   CheckoutForm1CountryOption,
+  CheckoutForm1ShippingOption,
+  CheckoutForm1Totals,
+  CheckoutForm1TotalsState,
 } from './blocks/e-commerce/checkout-forms/checkout-form-1'
 export type {
   CheckoutForm2Props,
@@ -168,9 +205,22 @@ export type { Verify1Props } from './blocks/application/verification/verify-1'
 export type { CanonMoney, CanonProduct } from './lib/contracts'
 export { PRODUCT_IMAGE_FALLBACK } from './lib/contracts'
 export {
+  isCompleteFiniteDecimal,
+  isAvailableMoney,
+  formatMoney,
+} from './lib/money'
+export { resolveAbsoluteQuantity } from './lib/cart'
+export {
+  moneySchema,
+  cartTotalsSchema,
+  productDetailProductSchema,
+  productDetailVariantSchema,
+  productOverview1PropsSchema,
   buttonPropsSchema,
   storeContainer1PropsSchema,
   productCard1PropsSchema,
+  productPresentationSchema,
+  productShowcase1PropsSchema,
   shoppingCart4PropsSchema,
   navbar4PropsSchema,
   paymentMethodSchema,
@@ -184,9 +234,15 @@ export {
   accountMenuItemSchema,
 } from './lib/contracts'
 export type {
+  ProductDetailProductSpec,
+  ProductDetailVariantSpec,
+  ProductOverview1SpecProps,
+  CartTotals,
   ButtonSpecProps,
   StoreContainer1SpecProps,
   ProductCard1SpecProps,
+  ProductPresentation,
+  ProductShowcase1SpecProps,
   ShoppingCart4SpecProps,
   Navbar4SpecProps,
   CardProduct,

package/src/lib/cart.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest'
+import { resolveAbsoluteQuantity } from './cart'
+
+describe('resolveAbsoluteQuantity', () => {
+  it('converts a Navbar DELTA into an ABSOLUTE quantity against the authoritative current quantity', () => {
+    expect(resolveAbsoluteQuantity(3, -1)).toBe(2)
+    expect(resolveAbsoluteQuantity(3, 1)).toBe(4)
+    expect(resolveAbsoluteQuantity(1, 1)).toBe(2)
+  })
+
+  it('never drops below one — removal is a distinct callback, not a zero quantity', () => {
+    expect(resolveAbsoluteQuantity(1, -1)).toBe(1)
+    expect(resolveAbsoluteQuantity(0, -1)).toBe(1)
+  })
+})

package/src/lib/cart.ts

@@ -0,0 +1,11 @@
+/**
+ * Cart line quantity normalization shared by the curated cart surfaces.
+ *
+ * The Navbar mini-cart expresses a quantity DELTA while the cart page reports
+ * an ABSOLUTE quantity. The boundary normalizes the delta against the
+ * authoritative current line quantity (from the backend cart) before mutating;
+ * it must never reinterpret one as the other.
+ */
+export function resolveAbsoluteQuantity(currentQuantity: number, delta: number): number {
+  return Math.max(1, currentQuantity + delta)
+}