@thorprovider/blocks 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/.turbo/turbo-build.log +15 -15
  2. package/.turbo/turbo-test.log +32 -5
  3. package/AGENTS.md +1 -1
  4. package/README.md +52 -0
  5. package/dist/.tsbuildinfo +1 -1
  6. package/dist/contracts.d.mts +1111 -90
  7. package/dist/contracts.d.ts +1111 -90
  8. package/dist/contracts.js +189 -6
  9. package/dist/contracts.js.map +1 -1
  10. package/dist/contracts.mjs +173 -7
  11. package/dist/contracts.mjs.map +1 -1
  12. package/dist/index.d.mts +467 -89
  13. package/dist/index.d.ts +467 -89
  14. package/dist/index.js +2967 -2250
  15. package/dist/index.js.map +1 -1
  16. package/dist/index.mjs +2989 -2282
  17. package/dist/index.mjs.map +1 -1
  18. package/docs/standards/theming.md +32 -5
  19. package/package.json +4 -3
  20. package/src/blocks/e-commerce/category-filters/category-filter-2-filter-panel.tsx +136 -93
  21. package/src/blocks/e-commerce/category-filters/category-filter-2.test.tsx +513 -0
  22. package/src/blocks/e-commerce/category-filters/category-filter-2.tsx +728 -148
  23. package/src/blocks/e-commerce/checkout-forms/checkout-confirmation-fulfilment-progress.tsx +14 -8
  24. package/src/blocks/e-commerce/checkout-forms/checkout-confirmation.test.tsx +136 -0
  25. package/src/blocks/e-commerce/checkout-forms/checkout-confirmation.tsx +145 -99
  26. package/src/blocks/e-commerce/checkout-forms/checkout-form-1-order-summary.tsx +215 -102
  27. package/src/blocks/e-commerce/checkout-forms/checkout-form-1-payment-step.tsx +6 -2
  28. package/src/blocks/e-commerce/checkout-forms/checkout-form-1-shipping-step.tsx +51 -2
  29. package/src/blocks/e-commerce/checkout-forms/checkout-form-1.test.tsx +216 -0
  30. package/src/blocks/e-commerce/checkout-forms/checkout-form-1.tsx +114 -11
  31. package/src/blocks/e-commerce/navigation/mobile-category-drawer.test.tsx +42 -2
  32. package/src/blocks/e-commerce/navigation/mobile-category-drawer.tsx +10 -8
  33. package/src/blocks/e-commerce/product-categories/product-category-2.test.tsx +51 -0
  34. package/src/blocks/e-commerce/product-categories/product-category-2.tsx +56 -36
  35. package/src/blocks/e-commerce/product-overview/product-overview-1.test.tsx +182 -0
  36. package/src/blocks/e-commerce/product-overview/product-overview-1.tsx +298 -129
  37. package/src/blocks/e-commerce/shopping-carts/shopping-cart-4.test.tsx +137 -0
  38. package/src/blocks/e-commerce/shopping-carts/shopping-cart-4.tsx +231 -89
  39. package/src/blocks/e-commerce/storefront-hero/storefront-hero-1.test.tsx +65 -0
  40. package/src/blocks/e-commerce/storefront-hero/storefront-hero-1.tsx +19 -0
  41. package/src/blocks/marketing/footers/footer-section-1.test.tsx +117 -0
  42. package/src/blocks/marketing/footers/footer-section-1.tsx +46 -9
  43. package/src/blocks/marketing/navbars/navbar-4-cart-sheet.test.tsx +54 -0
  44. package/src/blocks/marketing/navbars/navbar-4-cart-sheet.tsx +43 -13
  45. package/src/blocks/marketing/navbars/navbar-4.test.tsx +112 -0
  46. package/src/blocks/marketing/navbars/navbar-4.tsx +101 -28
  47. package/src/index.ts +38 -0
  48. package/src/lib/cart.test.ts +15 -0
  49. package/src/lib/cart.ts +11 -0
  50. package/src/lib/contracts-curated.test.ts +207 -0
  51. package/src/lib/contracts-server-boundary.test.ts +52 -0
  52. package/src/lib/contracts.ts +182 -4
  53. package/src/lib/money.test.ts +64 -0
  54. package/src/lib/money.ts +65 -0
  55. package/styles.css +1 -0
  56. package/tsup.config.ts +0 -1
  57. package/vitest.config.ts +9 -1
package/dist/index.d.ts CHANGED
@@ -5,10 +5,10 @@ import { ReactNode, JSX } from 'react';
5
5
  import { VariantProps } from 'class-variance-authority';
6
6
  import { Avatar as Avatar$1 } from 'radix-ui';
7
7
  import { LucideIcon } from 'lucide-react';
8
+ import { Money, ProductOption, SelectedOption, Image, PaymentMethod } from '@thorprovider/types';
8
9
  import { StoreCategory } from './contracts.js';
9
- export { AccountMenuItem, ButtonSpecProps, CanonMoney, CanonProduct, CardProduct, CartItem, NavCartItem, Navbar4SpecProps, PRODUCT_IMAGE_FALLBACK, ProductCard1SpecProps, Promotion, ShoppingCart4SpecProps, StoreContainer1SpecProps, StoreUser, UtilityLink, accountMenuItemSchema, buttonPropsSchema, cardProductSchema, cartItemSchema, navCartItemSchema, navbar4PropsSchema, paymentMethodSchema, productCard1PropsSchema, promotionSchema, shoppingCart4PropsSchema, storeCategorySchema, storeContainer1PropsSchema, storeUserSchema, utilityLinkSchema } from './contracts.js';
10
+ export { AccountMenuItem, ButtonSpecProps, CanonMoney, CanonProduct, CardProduct, CartItem, CartTotals, NavCartItem, Navbar4SpecProps, PRODUCT_IMAGE_FALLBACK, ProductCard1SpecProps, ProductDetailProductSpec, ProductDetailVariantSpec, ProductOverview1SpecProps, Promotion, ShoppingCart4SpecProps, StoreContainer1SpecProps, StoreUser, UtilityLink, accountMenuItemSchema, buttonPropsSchema, cardProductSchema, cartItemSchema, cartTotalsSchema, formatMoney, isAvailableMoney, isCompleteFiniteDecimal, moneySchema, navCartItemSchema, navbar4PropsSchema, paymentMethodSchema, productCard1PropsSchema, productDetailProductSchema, productDetailVariantSchema, productOverview1PropsSchema, promotionSchema, resolveAbsoluteQuantity, shoppingCart4PropsSchema, storeCategorySchema, storeContainer1PropsSchema, storeUserSchema, utilityLinkSchema } from './contracts.js';
10
11
  import { z } from 'zod';
11
- import { PaymentMethod } from '@thorprovider/types';
12
12
 
13
13
  /**
14
14
  * Merge Tailwind CSS class names safely.
@@ -22,15 +22,15 @@ interface CTA {
22
22
  }
23
23
 
24
24
  declare const badgeVariants: (props?: ({
25
- variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | null | undefined;
25
+ variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
26
26
  } & class_variance_authority_types.ClassProp) | undefined) => string;
27
27
  declare function Badge({ className, variant, asChild, ...props }: react.ComponentProps<"span"> & VariantProps<typeof badgeVariants> & {
28
28
  asChild?: boolean;
29
29
  }): react.JSX.Element;
30
30
 
31
31
  declare const buttonVariants: (props?: ({
32
- variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | null | undefined;
33
- size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
32
+ variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
33
+ size?: "icon" | "default" | "xs" | "sm" | "lg" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
34
34
  } & class_variance_authority_types.ClassProp) | undefined) => string;
35
35
  declare function Button({ className, variant, size, asChild, ...props }: react.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
36
36
  asChild?: boolean;
@@ -151,12 +151,14 @@ interface AccountMenuItem {
151
151
  }
152
152
 
153
153
  interface CartItem {
154
+ /** Backend cart line-item id — the stable identity for update/removal. */
154
155
  id: string;
155
156
  name: string;
156
- variant: string;
157
+ variant?: string;
157
158
  price: number;
158
159
  qty: number;
159
- image: string;
160
+ /** Optional; an absent image is omitted rather than serialized as `""`. */
161
+ image?: string;
160
162
  }
161
163
 
162
164
  interface UtilityLink {
@@ -164,27 +166,66 @@ interface UtilityLink {
164
166
  href: string;
165
167
  }
166
168
 
169
+ interface LogoAccent {
170
+ /** Trailing segment of `logoText` to render with the accent styling. */
171
+ text: string;
172
+ /** Consumer-supplied classes for the accent span (e.g. a brand color token). */
173
+ className?: string;
174
+ }
167
175
  interface Navbar4Props {
168
176
  storeCategories: StoreCategory[];
169
177
  shippingNote: string;
170
178
  utilityLinks: UtilityLink[];
171
179
  logoText: string;
172
180
  logoHref?: string;
181
+ /**
182
+ * Optional accent for a trailing segment of `logoText` (e.g. the "Cuba" in
183
+ * "ElectroCuba"). When omitted, or when `text` is not a trailing segment of
184
+ * `logoText`, the wordmark renders unchanged.
185
+ */
186
+ logoAccent?: LogoAccent;
173
187
  /** When provided, a mobile-only "Account" link is appended to the utility links. */
174
188
  accountHref?: string;
189
+ /**
190
+ * When `false`, no search control is rendered at all — neither the desktop
191
+ * input, the mobile trigger, nor the mobile panel. Defaults to `true` so
192
+ * legacy consumers keep the existing self-contained search. The generated
193
+ * storefront passes `false` while no verified global search contract exists
194
+ * (E2 task 5.4), so no global search is presented as working.
195
+ */
196
+ showSearch?: boolean;
175
197
  searchQuery?: string;
176
198
  onSearchChange?: (value: string) => void;
177
199
  items?: CartItem[];
200
+ /**
201
+ * Quantity DELTA for a backend cart line-item id. The boundary converts the
202
+ * delta into an absolute quantity against the authoritative current line
203
+ * quantity before mutating the cart.
204
+ */
178
205
  onQtyChange?: (id: string, delta: number) => void;
206
+ /** Remove the backend cart line-item id. */
179
207
  onRemove?: (id: string) => void;
208
+ /** Authoritative backend subtotal for the mini-cart. */
209
+ subtotal?: Money;
210
+ /** Shown when an authoritative subtotal is supplied but absent/malformed. */
211
+ subtotalUnavailableLabel?: string;
212
+ /** Override money formatting (locale, currency). Defaults to `Money.currencyCode`. */
213
+ formatMoney?: (money: Money) => string;
180
214
  user?: StoreUser;
181
215
  accountMenuItems?: AccountMenuItem[];
182
216
  onHelp?: () => void;
183
217
  onSignOut?: () => void;
184
218
  onCheckout?: () => void;
185
219
  onViewCart?: () => void;
220
+ /**
221
+ * Consumer-supplied classes merged onto the outer `<header>` as the final
222
+ * argument, so a semantic surface such as `bg-brand-nav
223
+ * text-brand-nav-foreground` overrides the default `bg-background`. Purely
224
+ * presentational: no layout, structure, or behavior changes.
225
+ */
226
+ className?: string;
186
227
  }
187
- declare function Navbar4({ storeCategories, shippingNote, utilityLinks, logoText, logoHref, accountHref, searchQuery: searchQueryProp, onSearchChange, items: itemsProp, onQtyChange: onQtyChangeProp, onRemove: onRemoveProp, user, accountMenuItems, onHelp, onSignOut, onCheckout, onViewCart, }: Navbar4Props): react.JSX.Element;
228
+ declare function Navbar4({ storeCategories, shippingNote, utilityLinks, logoText, logoHref, logoAccent, accountHref, showSearch, searchQuery: searchQueryProp, onSearchChange, items: itemsProp, onQtyChange: onQtyChangeProp, onRemove: onRemoveProp, subtotal, subtotalUnavailableLabel, formatMoney, user, accountMenuItems, onHelp, onSignOut, onCheckout, onViewCart, className, }: Navbar4Props): react.JSX.Element;
188
229
 
189
230
  type Banner1Shape = 'bar' | 'pill';
190
231
  interface Banner1Props {
@@ -391,15 +432,39 @@ interface FooterLinkColumn$1 {
391
432
  interface FooterNewsletter {
392
433
  placeholder?: string;
393
434
  buttonLabel: string;
435
+ /**
436
+ * Submit handler. The interactive form (input + submit button) renders only
437
+ * when this is supplied. A newsletter without `onSubmit` renders no form,
438
+ * input, or button — never a fake form.
439
+ */
394
440
  onSubmit?: (email: string) => void;
395
441
  }
442
+ interface BrandAccent {
443
+ /** Trailing segment of `brandName` to render with the accent styling. */
444
+ text: string;
445
+ /** Consumer-supplied classes for the accent span (e.g. a brand color token). */
446
+ className?: string;
447
+ }
396
448
  interface FooterSection1Props {
397
449
  brandName: string;
450
+ /**
451
+ * Optional accent for a trailing segment of `brandName` (e.g. the "Cuba" in
452
+ * "ElectroCuba"). When omitted, or when `text` is not a trailing segment of
453
+ * `brandName`, the brand name renders unchanged.
454
+ */
455
+ brandAccent?: BrandAccent;
398
456
  brandDescription?: string;
399
457
  linkColumns: FooterLinkColumn$1[];
400
458
  newsletter?: FooterNewsletter;
459
+ /**
460
+ * Consumer-supplied classes merged onto the outer `<footer>` as the final
461
+ * argument, so a semantic surface such as `bg-brand-nav
462
+ * text-brand-nav-foreground` overrides the default `bg-secondary`. Purely
463
+ * presentational: no layout, structure, or behavior changes.
464
+ */
465
+ className?: string;
401
466
  }
402
- declare function FooterSection1({ brandName, brandDescription, linkColumns, newsletter, }: FooterSection1Props): react.JSX.Element;
467
+ declare function FooterSection1({ brandName, brandAccent, brandDescription, linkColumns, newsletter, className, }: FooterSection1Props): react.JSX.Element;
403
468
 
404
469
  interface FooterLink {
405
470
  label: string;
@@ -573,39 +638,76 @@ interface ProductCard5Props {
573
638
  }
574
639
  declare function ProductCard5({ products, onToggleWishlist, onAddToCart, onQuickView, onCompare, onExport, }: ProductCard5Props): react.JSX.Element;
575
640
 
576
- interface ProductOverview1ProductImage {
577
- id: number;
578
- src: string;
579
- alt: string;
580
- }
581
- interface ProductOverview1ProductColor {
582
- name: string;
583
- value: string;
584
- }
585
- interface ProductOverview1Product {
641
+ /**
642
+ * Canonical product-detail projection.
643
+ *
644
+ * The block consumes the canonical `@thorprovider/types` shapes (`Money`,
645
+ * `ProductOption`, `SelectedOption`, `Image`) so adapter output maps without a
646
+ * second, drifting product type. The only deviation is `price`: the canon marks
647
+ * it required, but a missing/unresolved backend price is a real, distinct state
648
+ * that must disable purchase — so the projection allows `price` to be absent
649
+ * and the block treats absence as "unavailable", never as zero.
650
+ */
651
+ interface ProductDetailVariant {
586
652
  id: string;
587
- brand: string;
588
- name: string;
589
- description: string;
590
- price: number;
591
- currency: string;
592
- rating: number;
593
- images: ProductOverview1ProductImage[];
594
- sizes: number[];
595
- colors: ProductOverview1ProductColor[];
653
+ title: string;
654
+ sku?: string;
655
+ availableForSale: boolean;
656
+ selectedOptions: SelectedOption[];
657
+ /** Canonical Money; omit/null when the backend has no resolved price. */
658
+ price?: Money | null;
659
+ compareAtPrice?: Money;
660
+ image?: Image;
661
+ }
662
+ interface ProductDetailProduct {
663
+ id: string;
664
+ handle?: string;
665
+ title: string;
666
+ description?: string;
667
+ vendor?: string;
668
+ options: ProductOption[];
669
+ variants: ProductDetailVariant[];
670
+ images: Image[];
671
+ featuredImage?: Image;
672
+ }
673
+ interface ProductOverview1Rating {
674
+ value: number;
675
+ count: number;
596
676
  }
597
677
  interface ProductOverview1Props {
598
- product: ProductOverview1Product;
678
+ product: ProductDetailProduct;
679
+ /** Controlled selection: the backend variant id, or null/undefined when nothing is explicitly selected. */
680
+ selectedVariantId?: string | null;
681
+ onSelectVariant?: (variantId: string) => void;
682
+ /** Controlled quantity for the add-to-cart action; defaults to 1 when omitted. */
683
+ quantity?: number;
684
+ onQuantityChange?: (quantity: number) => void;
685
+ /** Add-to-cart identity is the selected backend variant id, with the requested quantity. */
686
+ onAddToCart?: (variantId: string, quantity: number) => void;
687
+ isWishlisted?: boolean;
688
+ onToggleWishlist?: (variantId: string, isWishlisted: boolean) => void;
689
+ /** Rendered only when the backend supplies it. */
690
+ rating?: ProductOverview1Rating;
691
+ /** Rendered only when the backend supplies it. */
692
+ deliveryEstimate?: string;
693
+ /** Rendered only when the backend supplies it. */
694
+ shipping?: Money;
695
+ formatPrice?: (money: Money) => string;
599
696
  sizesLabel?: string;
600
- colorLabel?: string;
697
+ variantLabel?: string;
601
698
  reviewsLabel?: string;
602
699
  addToCartLabel?: string;
700
+ outOfStockLabel?: string;
701
+ unavailablePriceLabel?: string;
702
+ selectVariantLabel?: string;
703
+ quantityLabel?: string;
704
+ deliveryEstimateLabel?: string;
705
+ shippingLabel?: string;
603
706
  removeFromWishlistLabel?: string;
604
707
  addToWishlistLabel?: string;
605
- onAddToCart?: (product: ProductOverview1Product) => void;
606
- onToggleWishlist?: (product: ProductOverview1Product, isWishlisted: boolean) => void;
708
+ imageFallback?: string;
607
709
  }
608
- declare function ProductOverview1({ product, sizesLabel, colorLabel, reviewsLabel, addToCartLabel, removeFromWishlistLabel, addToWishlistLabel, onAddToCart, onToggleWishlist, }: ProductOverview1Props): react.JSX.Element;
710
+ declare function ProductOverview1({ product, selectedVariantId, onSelectVariant, quantity, onQuantityChange, onAddToCart, isWishlisted, onToggleWishlist, rating, deliveryEstimate, shipping, formatPrice, sizesLabel, variantLabel, reviewsLabel, addToCartLabel, outOfStockLabel, unavailablePriceLabel, selectVariantLabel, quantityLabel, deliveryEstimateLabel, shippingLabel, removeFromWishlistLabel, addToWishlistLabel, imageFallback, }: ProductOverview1Props): react.JSX.Element;
609
711
 
610
712
  interface ProductOverview2ProductImage {
611
713
  src: string;
@@ -855,7 +957,12 @@ interface ProductCategory2Category {
855
957
  handle?: string;
856
958
  name: string;
857
959
  description: string;
858
- itemCount: number;
960
+ /**
961
+ * Number of items in the category. Optional: when omitted, or when it is not
962
+ * a finite non-negative number, no count is rendered — an unknown projection
963
+ * must not be shown as a fabricated `0`. A real `0` is preserved.
964
+ */
965
+ itemCount?: number;
859
966
  image: string;
860
967
  trending: boolean;
861
968
  }
@@ -937,17 +1044,17 @@ declare const collectionItemSchema: z.ZodObject<{
937
1044
  image: z.ZodOptional<z.ZodString>;
938
1045
  href: z.ZodOptional<z.ZodString>;
939
1046
  }, "strip", z.ZodTypeAny, {
940
- label: string;
941
1047
  id: string;
1048
+ label: string;
942
1049
  image?: string | undefined;
943
- href?: string | undefined;
944
1050
  description?: string | undefined;
1051
+ href?: string | undefined;
945
1052
  }, {
946
- label: string;
947
1053
  id: string;
1054
+ label: string;
948
1055
  image?: string | undefined;
949
- href?: string | undefined;
950
1056
  description?: string | undefined;
1057
+ href?: string | undefined;
951
1058
  }>;
952
1059
  type CollectionItem = z.infer<typeof collectionItemSchema>;
953
1060
 
@@ -991,17 +1098,17 @@ declare const megaMenuPropsSchema: z.ZodObject<{
991
1098
  image: z.ZodOptional<z.ZodString>;
992
1099
  href: z.ZodOptional<z.ZodString>;
993
1100
  }, "strip", z.ZodTypeAny, {
994
- label: string;
995
1101
  id: string;
1102
+ label: string;
996
1103
  image?: string | undefined;
997
- href?: string | undefined;
998
1104
  description?: string | undefined;
1105
+ href?: string | undefined;
999
1106
  }, {
1000
- label: string;
1001
1107
  id: string;
1108
+ label: string;
1002
1109
  image?: string | undefined;
1003
- href?: string | undefined;
1004
1110
  description?: string | undefined;
1111
+ href?: string | undefined;
1005
1112
  }>, "many">;
1006
1113
  onNavigate: z.ZodOptional<z.ZodType<() => void, z.ZodTypeDef, () => void>>;
1007
1114
  categoryColumnTitle: z.ZodOptional<z.ZodString>;
@@ -1021,11 +1128,11 @@ declare const megaMenuPropsSchema: z.ZodObject<{
1021
1128
  children?: MenuItem[];
1022
1129
  }[];
1023
1130
  collections: {
1024
- label: string;
1025
1131
  id: string;
1132
+ label: string;
1026
1133
  image?: string | undefined;
1027
- href?: string | undefined;
1028
1134
  description?: string | undefined;
1135
+ href?: string | undefined;
1029
1136
  }[];
1030
1137
  onNavigate?: (() => void) | undefined;
1031
1138
  categoryColumnTitle?: string | undefined;
@@ -1045,11 +1152,11 @@ declare const megaMenuPropsSchema: z.ZodObject<{
1045
1152
  children?: MenuItem[];
1046
1153
  }[];
1047
1154
  collections: {
1048
- label: string;
1049
1155
  id: string;
1156
+ label: string;
1050
1157
  image?: string | undefined;
1051
- href?: string | undefined;
1052
1158
  description?: string | undefined;
1159
+ href?: string | undefined;
1053
1160
  }[];
1054
1161
  onNavigate?: (() => void) | undefined;
1055
1162
  categoryColumnTitle?: string | undefined;
@@ -1101,17 +1208,17 @@ declare const mobileCategoryDrawerPropsSchema: z.ZodObject<{
1101
1208
  image: z.ZodOptional<z.ZodString>;
1102
1209
  href: z.ZodOptional<z.ZodString>;
1103
1210
  }, "strip", z.ZodTypeAny, {
1104
- label: string;
1105
1211
  id: string;
1212
+ label: string;
1106
1213
  image?: string | undefined;
1107
- href?: string | undefined;
1108
1214
  description?: string | undefined;
1215
+ href?: string | undefined;
1109
1216
  }, {
1110
- label: string;
1111
1217
  id: string;
1218
+ label: string;
1112
1219
  image?: string | undefined;
1113
- href?: string | undefined;
1114
1220
  description?: string | undefined;
1221
+ href?: string | undefined;
1115
1222
  }>, "many">;
1116
1223
  open: z.ZodBoolean;
1117
1224
  onClose: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodVoid>;
@@ -1135,11 +1242,11 @@ declare const mobileCategoryDrawerPropsSchema: z.ZodObject<{
1135
1242
  children?: MenuItem[];
1136
1243
  }[];
1137
1244
  collections: {
1138
- label: string;
1139
1245
  id: string;
1246
+ label: string;
1140
1247
  image?: string | undefined;
1141
- href?: string | undefined;
1142
1248
  description?: string | undefined;
1249
+ href?: string | undefined;
1143
1250
  }[];
1144
1251
  onClose: (...args: unknown[]) => void;
1145
1252
  collectionsTitle?: string | undefined;
@@ -1162,11 +1269,11 @@ declare const mobileCategoryDrawerPropsSchema: z.ZodObject<{
1162
1269
  children?: MenuItem[];
1163
1270
  }[];
1164
1271
  collections: {
1165
- label: string;
1166
1272
  id: string;
1273
+ label: string;
1167
1274
  image?: string | undefined;
1168
- href?: string | undefined;
1169
1275
  description?: string | undefined;
1276
+ href?: string | undefined;
1170
1277
  }[];
1171
1278
  onClose: (...args: unknown[]) => void;
1172
1279
  collectionsTitle?: string | undefined;
@@ -1190,11 +1297,11 @@ declare const categoryIconPropsSchema: z.ZodObject<{
1190
1297
  name: z.ZodOptional<z.ZodEnum<["wrench", "bolt", "tree", "refrigerator", "wind", "droplet", "zap", "hard-hat", "car", "utensils", "boxes", "sofa", "shield", "sun", "chef-hat", "tractor", "store", "home"]>>;
1191
1298
  className: z.ZodOptional<z.ZodString>;
1192
1299
  }, "strip", z.ZodTypeAny, {
1193
- className?: string | undefined;
1194
1300
  name?: "tree" | "home" | "wrench" | "bolt" | "refrigerator" | "wind" | "droplet" | "zap" | "hard-hat" | "car" | "utensils" | "boxes" | "sofa" | "shield" | "sun" | "chef-hat" | "tractor" | "store" | undefined;
1195
- }, {
1196
1301
  className?: string | undefined;
1302
+ }, {
1197
1303
  name?: "tree" | "home" | "wrench" | "bolt" | "refrigerator" | "wind" | "droplet" | "zap" | "hard-hat" | "car" | "utensils" | "boxes" | "sofa" | "shield" | "sun" | "chef-hat" | "tractor" | "store" | undefined;
1304
+ className?: string | undefined;
1198
1305
  }>;
1199
1306
  type CategoryIconProps = z.infer<typeof categoryIconPropsSchema>;
1200
1307
  /**
@@ -1242,12 +1349,24 @@ interface FilterProduct {
1242
1349
  id: string;
1243
1350
  name: string;
1244
1351
  price: string;
1245
- image: string;
1352
+ /** Optional: an absent image is omitted so the block never renders `src=""`. */
1353
+ image?: string;
1354
+ /**
1355
+ * Optional product-detail link. When present the card renders as a real
1356
+ * `<a href>` (keyboard focus, middle-click, crawlers); when absent the block
1357
+ * falls back to the `onProductClick` path. The href is produced by the
1358
+ * presentation layer — the block never builds a route.
1359
+ */
1360
+ href?: string;
1246
1361
  }
1247
1362
  interface CategoryFilter2Category {
1248
1363
  id: string;
1249
1364
  label: string;
1250
1365
  }
1366
+ interface CategoryFilter2Collection {
1367
+ id: string;
1368
+ label: string;
1369
+ }
1251
1370
  interface CategoryFilter2Color {
1252
1371
  id: string;
1253
1372
  color: string;
@@ -1263,19 +1382,99 @@ interface CategoryFilter2SortOption {
1263
1382
  }
1264
1383
  interface CategoryFilter2Filters {
1265
1384
  categories: string[];
1385
+ /** Collections requested by the `category-filters` feature (E2). */
1386
+ collections?: string[];
1266
1387
  priceRange: number[];
1267
1388
  size: string | null;
1268
1389
  color: string | null;
1269
1390
  }
1391
+ /**
1392
+ * A typed catalog-query error the listing renders for repair. It is a structural
1393
+ * mirror of the runtime boundary error (`CatalogQueryError`/`CatalogQueryFailure`):
1394
+ * `fields` names the exact raw parameters to remove and `feature` is present only
1395
+ * for `unmounted-capability`. The block never builds a host URL — it emits the
1396
+ * fields through `onRepair` (E2 task 4.5).
1397
+ */
1398
+ interface CategoryFilter2QueryError {
1399
+ code: 'invalid-query' | 'unsupported-query' | 'unmounted-capability';
1400
+ /** Exact raw URL parameter names that must be removed to repair the query. */
1401
+ fields: string[];
1402
+ message?: string;
1403
+ feature?: 'catalog-search' | 'category-filters';
1404
+ }
1405
+ /**
1406
+ * The observable listing status. The host derives it from the URL boundary and
1407
+ * the provider outcome (`mapCatalogOutcomeToStatus`) and passes it down; the
1408
+ * block only renders it. `loading` is in flight; `ready` shows products; `empty`
1409
+ * is a valid zero-result query; `invalid-query`/`unsupported-query`/
1410
+ * `unmounted-capability` are typed repair states; `error` is a query/network
1411
+ * failure with retry. Distinct states stay distinct — a valid empty result is
1412
+ * never shown as an error and a raw failure is never swallowed as empty.
1413
+ */
1414
+ type CategoryFilter2Status = {
1415
+ state: 'loading';
1416
+ } | {
1417
+ state: 'ready';
1418
+ } | {
1419
+ state: 'empty';
1420
+ } | {
1421
+ state: 'invalid-query';
1422
+ error: CategoryFilter2QueryError;
1423
+ } | {
1424
+ state: 'unsupported-query';
1425
+ error: CategoryFilter2QueryError;
1426
+ } | {
1427
+ state: 'unmounted-capability';
1428
+ error: CategoryFilter2QueryError;
1429
+ } | {
1430
+ state: 'error';
1431
+ message?: string;
1432
+ };
1433
+ /** The kind of canonical filter an active chip represents. */
1434
+ type CategoryFilter2ActiveFilterKind = 'text' | 'category' | 'collection' | 'price' | 'attribute';
1435
+ /**
1436
+ * A removable active-filter chip. Built only from the actual canonical query
1437
+ * (never from claimed provider filtering): `params` are the raw URL parameter
1438
+ * names carrying the filter and `value` is the specific list value to drop.
1439
+ */
1440
+ interface CategoryFilter2ActiveFilter {
1441
+ /** Stable identity for React keys and removal callbacks. */
1442
+ id: string;
1443
+ kind: CategoryFilter2ActiveFilterKind;
1444
+ /** Human-readable label shown on the chip. */
1445
+ label: string;
1446
+ /** Raw URL parameter names that carry this filter. */
1447
+ params: string[];
1448
+ /** The specific list value this chip removes; absent for scalar filters. */
1449
+ value?: string;
1450
+ }
1270
1451
  interface CategoryFilter2Props {
1271
1452
  products: FilterProduct[];
1272
1453
  categories?: CategoryFilter2Category[];
1454
+ collections?: CategoryFilter2Collection[];
1273
1455
  sizes?: string[];
1274
1456
  colors?: CategoryFilter2Color[];
1457
+ /**
1458
+ * Real backend-provided price range only. When absent the price control is
1459
+ * omitted; the block never falls back to a fabricated `0..1000` default
1460
+ * (E2 design Decision 8 / spec "Price controls require real price metadata").
1461
+ */
1275
1462
  priceRange?: CategoryFilter2PriceRange;
1276
1463
  viewOptions?: (number | string)[];
1464
+ /** Adapter-advertised sort options only. When absent/empty no sort control is rendered. */
1277
1465
  sortOptions?: CategoryFilter2SortOption[];
1278
1466
  pagination?: (number | string)[];
1467
+ searchValue?: string;
1468
+ selectedCategories?: string[];
1469
+ selectedCollections?: string[];
1470
+ selectedPriceRange?: number[];
1471
+ selectedSort?: string;
1472
+ selectedPage?: number | string;
1473
+ selectedPageSize?: number | string;
1474
+ showSearch?: boolean;
1475
+ showFilters?: boolean;
1476
+ showPrice?: boolean;
1477
+ showSort?: boolean;
1279
1478
  filtersTitle?: string;
1280
1479
  selectedText?: string;
1281
1480
  clearAllLabel?: string;
@@ -1283,6 +1482,7 @@ interface CategoryFilter2Props {
1283
1482
  minLabel?: string;
1284
1483
  maxLabel?: string;
1285
1484
  categoriesTitle?: string;
1485
+ collectionsTitle?: string;
1286
1486
  sizesTitle?: string;
1287
1487
  colorsTitle?: string;
1288
1488
  viewLabel?: string;
@@ -1290,13 +1490,72 @@ interface CategoryFilter2Props {
1290
1490
  sortPlaceholder?: string;
1291
1491
  productsTitle?: string;
1292
1492
  currentLabel?: string;
1493
+ searchLabel?: string;
1494
+ searchPlaceholder?: string;
1293
1495
  onProductClick?: (product: FilterProduct) => void;
1294
1496
  onPageChange?: (page: number | string) => void;
1295
1497
  onViewChange?: (view: number | string) => void;
1498
+ onPageSizeChange?: (pageSize: number | string) => void;
1296
1499
  onSortChange?: (sort: string) => void;
1297
1500
  onFilterChange?: (filters: CategoryFilter2Filters) => void;
1501
+ onSearchChange?: (text: string) => void;
1502
+ /** Observable listing status. Defaults to `ready` so legacy consumers are unchanged. */
1503
+ status?: CategoryFilter2Status;
1504
+ /** Removable active-filter chips built from the canonical query. */
1505
+ activeFilters?: CategoryFilter2ActiveFilter[];
1506
+ loadingLabel?: string;
1507
+ emptyTitle?: string;
1508
+ emptyDescription?: string;
1509
+ clearFiltersLabel?: string;
1510
+ invalidQueryTitle?: string;
1511
+ unsupportedQueryTitle?: string;
1512
+ unmountedCapabilityTitle?: string;
1513
+ errorTitle?: string;
1514
+ errorDescription?: string;
1515
+ repairLabel?: string;
1516
+ retryLabel?: string;
1517
+ activeFiltersTitle?: string;
1518
+ removeFilterLabel?: string;
1519
+ /** Empty-state clear: drops the active filters but never base scope/sort/pageSize. */
1520
+ onClearFilters?: () => void;
1521
+ /** Invalid/unsupported/unmounted repair: receives the exact bad fields to remove. */
1522
+ onRepair?: (remove: string[]) => void;
1523
+ /** Query/network failure retry: preserves the current query/input. */
1524
+ onRetry?: () => void;
1525
+ /** Removes a single active-filter chip. */
1526
+ onRemoveFilter?: (filter: CategoryFilter2ActiveFilter) => void;
1527
+ }
1528
+ interface CategoryFilter2StatusViewProps {
1529
+ status: CategoryFilter2Status;
1530
+ activeFilters?: CategoryFilter2ActiveFilter[];
1531
+ activeFiltersTitle?: string;
1532
+ removeFilterLabel?: string;
1533
+ loadingLabel?: string;
1534
+ emptyTitle?: string;
1535
+ emptyDescription?: string;
1536
+ clearFiltersLabel?: string;
1537
+ invalidQueryTitle?: string;
1538
+ unsupportedQueryTitle?: string;
1539
+ unmountedCapabilityTitle?: string;
1540
+ errorTitle?: string;
1541
+ errorDescription?: string;
1542
+ repairLabel?: string;
1543
+ retryLabel?: string;
1544
+ onClearFilters?: () => void;
1545
+ onRepair?: (remove: string[]) => void;
1546
+ onRetry?: () => void;
1547
+ onRemoveFilter?: (filter: CategoryFilter2ActiveFilter) => void;
1298
1548
  }
1299
- declare function CategoryFilter2({ products, categories, sizes, colors, priceRange: priceRangeConfig, viewOptions, sortOptions, pagination, filtersTitle, selectedText, clearAllLabel, priceRangeTitle, minLabel, maxLabel, categoriesTitle, sizesTitle, colorsTitle, viewLabel, viewPlaceholder, sortPlaceholder, productsTitle, currentLabel, onProductClick, onPageChange, onViewChange, onSortChange, onFilterChange, }: CategoryFilter2Props): react.JSX.Element;
1549
+ /**
1550
+ * Hooks-free presentation of the observable listing states and the removable
1551
+ * active-filter chips (E2 task 4.5). Kept separate from `CategoryFilter2` so the
1552
+ * interaction contract (clear / repair / retry / chip removal) is testable by
1553
+ * invoking the rendered handlers without a DOM (this package's tests render with
1554
+ * `react-dom/server`). It renders no products and performs no fetch — it only
1555
+ * emits the host callbacks. When `ready` with no chips it renders nothing.
1556
+ */
1557
+ declare function CategoryFilter2StatusView({ status, activeFilters, activeFiltersTitle, removeFilterLabel, loadingLabel, emptyTitle, emptyDescription, clearFiltersLabel, invalidQueryTitle, unsupportedQueryTitle, unmountedCapabilityTitle, errorTitle, errorDescription, repairLabel, retryLabel, onClearFilters, onRepair, onRetry, onRemoveFilter, }: CategoryFilter2StatusViewProps): react.JSX.Element | null;
1558
+ declare function CategoryFilter2({ products, categories, collections, sizes, colors, priceRange: priceRangeConfig, viewOptions, sortOptions, pagination, searchValue, selectedCategories, selectedCollections, selectedPriceRange, selectedSort, selectedPage, selectedPageSize, showSearch, showFilters, showPrice, showSort, filtersTitle, selectedText, clearAllLabel, priceRangeTitle, minLabel, maxLabel, categoriesTitle, collectionsTitle, sizesTitle, colorsTitle, viewLabel, viewPlaceholder, sortPlaceholder, productsTitle, currentLabel, searchLabel, searchPlaceholder, onProductClick, onPageChange, onViewChange, onPageSizeChange, onSortChange, onFilterChange, onSearchChange, status, activeFilters, loadingLabel, emptyTitle, emptyDescription, clearFiltersLabel, invalidQueryTitle, unsupportedQueryTitle, unmountedCapabilityTitle, errorTitle, errorDescription, repairLabel, retryLabel, activeFiltersTitle, removeFilterLabel, onClearFilters, onRepair, onRetry, onRemoveFilter, }: CategoryFilter2Props): react.JSX.Element;
1300
1559
 
1301
1560
  interface CategoryFilter4SortOption {
1302
1561
  value: string;
@@ -1465,13 +1724,27 @@ interface ShoppingCart2Props {
1465
1724
  declare function ShoppingCart2({ items, recommendations, taxRate, shippingCost, freeShippingThreshold, validatePromo, titleLabel, itemsCountLabel, cartItemsLabel, orderSummaryLabel, subtotalLabel, savingsLabel, shippingLabel, freeShippingLabel, taxLabel, totalLabel, promoPlaceholder, applyPromoLabel, promoAppliedLabel, continueShoppingLabel, emptyCartTitleLabel, emptyCartDescriptionLabel, checkoutLabel, freeShippingNoteLabel, freeShippingThresholdNoteLabel, secureCheckoutLabel, recommendationsLabel, onQuantityChange, onRemove, onAddToWishlist, onCheckout, onContinueShopping, onRecommendationClick, }: ShoppingCart2Props): react.JSX.Element;
1466
1725
 
1467
1726
  interface ShoppingCart4Item {
1727
+ /** Backend cart line-item id — the stable identity for update/removal. */
1468
1728
  id: string;
1469
1729
  name: string;
1470
1730
  price: number;
1471
1731
  quantity: number;
1472
- image: string;
1732
+ /** Optional; an absent image is omitted rather than serialized as `""`. */
1733
+ image?: string;
1473
1734
  variant?: string;
1474
- }
1735
+ /** Canonical backend per-unit price; preferred for display when present. */
1736
+ unitPrice?: Money;
1737
+ /** Canonical backend line total; preferred over `price * quantity`. */
1738
+ lineTotal?: Money;
1739
+ }
1740
+ interface ShoppingCart4Totals {
1741
+ subtotal: Money;
1742
+ discount?: Money;
1743
+ tax?: Money;
1744
+ shipping?: Money;
1745
+ total: Money;
1746
+ }
1747
+ type ShoppingCart4TotalsState = 'idle' | 'pending' | 'error';
1475
1748
  interface ShoppingCart4Promotion {
1476
1749
  threshold: number;
1477
1750
  reward: string;
@@ -1481,19 +1754,40 @@ interface ShoppingCart4RecentlyViewed {
1481
1754
  id: string;
1482
1755
  name: string;
1483
1756
  price: number;
1484
- image: string;
1757
+ image?: string;
1485
1758
  }
1486
1759
  interface ShoppingCart4Props {
1487
1760
  items: ShoppingCart4Item[];
1488
1761
  promotions: ShoppingCart4Promotion[];
1489
1762
  recentlyViewed?: ShoppingCart4RecentlyViewed[];
1763
+ /**
1764
+ * Backend-authoritative totals. The curated cart renders these verbatim; it
1765
+ * never computes subtotal/tax/shipping/total locally.
1766
+ */
1767
+ totals?: ShoppingCart4Totals;
1768
+ /** Controlled state of the totals fetch/mutation. */
1769
+ totalsState?: ShoppingCart4TotalsState;
1770
+ totalsErrorLabel?: string;
1771
+ /** Shown when a required total amount is absent or malformed (never as zero). */
1772
+ totalsUnavailableLabel?: string;
1773
+ /** Shown for a line whose supplied line total is absent or malformed. */
1774
+ amountUnavailableLabel?: string;
1775
+ retryLabel?: string;
1776
+ onRetryTotals?: () => void;
1777
+ /** Override money formatting (locale, currency). Defaults to `Money.currencyCode`. */
1778
+ formatMoney?: (money: Money) => string;
1779
+ /** @deprecated legacy numeric formatter, used only when `totals` is absent. */
1780
+ formatPrice?: (value: number) => string;
1781
+ /** @deprecated legacy local tax rate, used only when `totals` is absent. */
1490
1782
  taxRate?: number;
1491
1783
  titleLabel?: string;
1492
1784
  subtotalLabel?: string;
1785
+ discountLabel?: string;
1493
1786
  taxLabel?: string;
1494
1787
  shippingLabel?: string;
1495
1788
  shippingFreeLabel?: string;
1496
1789
  totalLabel?: string;
1790
+ totalsPendingLabel?: string;
1497
1791
  awayFromLabel?: string;
1498
1792
  activatedLabel?: string;
1499
1793
  itemsLabel?: string;
@@ -1508,7 +1802,16 @@ interface ShoppingCart4Props {
1508
1802
  checkoutLabel?: string;
1509
1803
  quickCheckoutLabel?: string;
1510
1804
  checkoutNowLabel?: string;
1805
+ emptyLabel?: string;
1806
+ removeLabel?: string;
1807
+ decreaseLabel?: string;
1808
+ increaseLabel?: string;
1809
+ /**
1810
+ * ABSOLUTE quantity for a backend cart line-item id (distinct from the
1811
+ * Navbar's DELTA). The boundary mutates the cart by line-item id.
1812
+ */
1511
1813
  onQuantityChange?: (id: string, quantity: number) => void;
1814
+ /** Remove the backend cart line-item id. */
1512
1815
  onRemove?: (id: string) => void;
1513
1816
  onCheckout?: () => void;
1514
1817
  onQuickCheckout?: () => void;
@@ -1516,7 +1819,7 @@ interface ShoppingCart4Props {
1516
1819
  onPayWithGoogle?: () => void;
1517
1820
  onRecentlyViewedClick?: (id: string) => void;
1518
1821
  }
1519
- declare function ShoppingCart4({ items, promotions, recentlyViewed, taxRate, titleLabel, subtotalLabel, taxLabel, shippingLabel, shippingFreeLabel, totalLabel, awayFromLabel, activatedLabel, itemsLabel, expressCheckoutLabel, expressLabel, standardLabel, estimatedDeliveryLabel, secureCheckoutLabel, recentlyViewedLabel, collapseLabel, expandLabel, checkoutLabel, quickCheckoutLabel, checkoutNowLabel, onQuantityChange, onRemove, onCheckout, onQuickCheckout, onPayWithApple, onPayWithGoogle, onRecentlyViewedClick, }: ShoppingCart4Props): react.JSX.Element;
1822
+ declare function ShoppingCart4({ items, promotions, recentlyViewed, totals, totalsState, totalsErrorLabel, totalsUnavailableLabel, amountUnavailableLabel, retryLabel, onRetryTotals, formatMoney: formatMoneyProp, formatPrice, titleLabel, subtotalLabel, discountLabel, taxLabel, shippingLabel, shippingFreeLabel, totalLabel, totalsPendingLabel, awayFromLabel, activatedLabel, itemsLabel, expressCheckoutLabel, expressLabel, standardLabel, estimatedDeliveryLabel, secureCheckoutLabel, recentlyViewedLabel, collapseLabel, expandLabel, checkoutLabel, quickCheckoutLabel, checkoutNowLabel, emptyLabel, removeLabel, decreaseLabel, increaseLabel, onQuantityChange, onRemove, onCheckout, onQuickCheckout, onPayWithApple, onPayWithGoogle, onRecentlyViewedClick, }: ShoppingCart4Props): react.JSX.Element;
1520
1823
 
1521
1824
  type ShoppingCart3Tag = 'Limited Edition' | 'Best Seller' | 'New Arrival';
1522
1825
  interface ShoppingCart3CartItem {
@@ -1610,32 +1913,82 @@ type CheckoutForm1FieldDescriptions = Partial<Record<keyof CheckoutForm1FormData
1610
1913
  interface CheckoutForm1OrderSummaryItem {
1611
1914
  id: string | number;
1612
1915
  name: string;
1613
- variant: string;
1614
- price: number;
1916
+ variant?: string;
1615
1917
  quantity: number;
1616
- image: string;
1918
+ /** Canonical backend line total; preferred over `price * quantity`. */
1919
+ lineTotal?: Money;
1920
+ /** @deprecated legacy numeric price, used only when `lineTotal` is absent. */
1921
+ price?: number;
1922
+ /** Optional; an absent image is omitted rather than serialized as `""`. */
1923
+ image?: string;
1924
+ }
1925
+ interface CheckoutForm1Totals {
1926
+ subtotal: Money;
1927
+ discount?: Money;
1928
+ tax?: Money;
1929
+ shipping?: Money;
1930
+ total: Money;
1617
1931
  }
1932
+ type CheckoutForm1TotalsState = 'idle' | 'pending' | 'error';
1618
1933
  interface CheckoutForm1OrderSummary {
1619
1934
  items: CheckoutForm1OrderSummaryItem[];
1620
- shipping: number;
1621
- tax: number;
1935
+ /** Backend-authoritative totals; rendered verbatim when present. */
1936
+ totals?: CheckoutForm1Totals;
1937
+ /** @deprecated legacy numeric amounts, used only when `totals` is absent. */
1938
+ shipping?: number;
1939
+ /** @deprecated */
1940
+ tax?: number;
1941
+ /** @deprecated */
1622
1942
  discount?: number;
1943
+ /** @deprecated */
1623
1944
  promoDiscount?: number;
1624
1945
  }
1625
1946
  interface CheckoutForm1CountryOption {
1626
1947
  value: string;
1627
1948
  label: string;
1628
1949
  }
1950
+ interface CheckoutForm1ShippingOption {
1951
+ /** Backend shipping method id — the controlled selection identity. */
1952
+ id: string;
1953
+ name: string;
1954
+ price?: Money;
1955
+ description?: string;
1956
+ estimatedDays?: string;
1957
+ }
1629
1958
  type CheckoutForm1ChangeHandler = (field: keyof CheckoutForm1FormData, value: string | boolean) => void;
1630
1959
  interface CheckoutForm1Props {
1631
1960
  title?: string;
1632
1961
  description?: string;
1633
1962
  orderSummary?: CheckoutForm1OrderSummary;
1963
+ /** Controlled state of the totals fetch/mutation. */
1964
+ totalsState?: CheckoutForm1TotalsState;
1965
+ totalsErrorLabel?: string;
1966
+ retryLabel?: string;
1967
+ onRetryTotals?: () => void;
1634
1968
  countries?: CheckoutForm1CountryOption[];
1969
+ /** Eligible shipping options for the cart's region/address. */
1970
+ shippingOptions?: CheckoutForm1ShippingOption[];
1971
+ /** Controlled selection of a shipping option id. */
1972
+ selectedShippingOptionId?: string;
1973
+ onSelectShippingOption?: (id: string) => void;
1635
1974
  paymentMethods?: PaymentMethod[];
1636
1975
  noPaymentMethodsLabel?: string;
1976
+ /** Override money formatting (locale, currency). Defaults to `Money.currencyCode`. */
1977
+ formatMoney?: (money: Money) => string;
1978
+ /**
1979
+ * Raw card fields are legacy-only and never collected in the launch flow.
1980
+ * Defaults to `false`: the curated surface renders no card inputs.
1981
+ */
1982
+ collectCardFields?: boolean;
1983
+ onApplyPromo?: (code: string) => void;
1984
+ promoPending?: boolean;
1985
+ promoApplyLabel?: string;
1986
+ promoPlaceholder?: string;
1987
+ /** Optional trust copy; rendered only when supplied (never fabricated). */
1988
+ trustNotes?: string[];
1637
1989
  backLabel?: string;
1638
1990
  completeOrderLabel?: string;
1991
+ processingLabel?: string;
1639
1992
  continueLabel?: string;
1640
1993
  values: CheckoutForm1FormData;
1641
1994
  onChange: CheckoutForm1ChangeHandler;
@@ -1647,8 +2000,11 @@ interface CheckoutForm1Props {
1647
2000
  submitting?: boolean;
1648
2001
  /** Order-level error surfaced above the footer actions. */
1649
2002
  submitError?: string;
2003
+ /** Optional recovery action for a failed submission. */
2004
+ onRetrySubmit?: () => void;
2005
+ submitErrorActionLabel?: string;
1650
2006
  }
1651
- declare function CheckoutForm1({ title, description, orderSummary, countries, paymentMethods, noPaymentMethodsLabel, backLabel, completeOrderLabel, continueLabel, values, onChange, fieldErrors, fieldDescriptions, validateStep, onSubmit, submitting, submitError, }: CheckoutForm1Props): react.JSX.Element;
2007
+ declare function CheckoutForm1({ title, description, orderSummary, totalsState, totalsErrorLabel, retryLabel, onRetryTotals, countries, shippingOptions, selectedShippingOptionId, onSelectShippingOption, paymentMethods, noPaymentMethodsLabel, formatMoney, collectCardFields, onApplyPromo, promoPending, promoApplyLabel, promoPlaceholder, trustNotes, backLabel, completeOrderLabel, processingLabel, continueLabel, values, onChange, fieldErrors, fieldDescriptions, validateStep, onSubmit, submitting, submitError, onRetrySubmit, submitErrorActionLabel, }: CheckoutForm1Props): react.JSX.Element;
1652
2008
 
1653
2009
  interface CheckoutForm2Item {
1654
2010
  id: string;
@@ -1831,10 +2187,13 @@ type FulfilmentStage = 'Confirmed' | 'Packed' | 'Shipped' | 'Delivered';
1831
2187
  interface OrderLine {
1832
2188
  id: string;
1833
2189
  name: string;
1834
- variant: string;
2190
+ variant?: string;
1835
2191
  quantity: number;
1836
- price: number;
1837
- image: string;
2192
+ /** Canonical backend line total. */
2193
+ lineTotal: Money;
2194
+ unitPrice?: Money;
2195
+ /** Optional; an absent image is omitted rather than serialized as `""`. */
2196
+ image?: string;
1838
2197
  }
1839
2198
  interface FulfilmentStageDetail {
1840
2199
  stage: FulfilmentStage;
@@ -1852,46 +2211,55 @@ interface FulfilmentStageDetail {
1852
2211
  interface OrderAddress {
1853
2212
  name: string;
1854
2213
  lines: string[];
1855
- method: string;
2214
+ method?: string;
1856
2215
  }
1857
2216
  interface OrderTotals {
1858
- subtotal: number;
1859
- shipping: number;
1860
- tax: number;
2217
+ subtotal?: Money;
2218
+ discount?: Money;
2219
+ shipping?: Money;
2220
+ tax?: Money;
2221
+ total?: Money;
1861
2222
  }
1862
2223
  interface Order$1 {
1863
2224
  number: string;
1864
2225
  /** ISO date */
1865
2226
  placedAt: string;
1866
- email: string;
1867
- currentStage: FulfilmentStage;
1868
- /** ISO date */
1869
- estimatedDelivery: string;
2227
+ email?: string;
2228
+ /** Present only when the backend reports a fulfilment stage. */
2229
+ currentStage?: FulfilmentStage;
2230
+ /** ISO date. Rendered only when supplied; no delivery estimate is fabricated. */
2231
+ estimatedDelivery?: string | null;
1870
2232
  trackingHref?: string;
1871
- shipping: OrderAddress;
1872
- billing: OrderAddress;
2233
+ shipping?: OrderAddress;
2234
+ billing?: OrderAddress;
1873
2235
  totals: OrderTotals;
1874
2236
  }
1875
2237
  interface CheckoutConfirmationProps {
1876
2238
  order: Order$1;
1877
2239
  orderLines: OrderLine[];
1878
2240
  /**
1879
- * Keyed by `FulfilmentStage`. The stage strip is ordered by `Object.keys`,
1880
- * so define the record in the canonical `Confirmed → Packed → Shipped → Delivered` order.
2241
+ * Keyed by `FulfilmentStage`. Rendered only when supplied; the stage strip is
2242
+ * ordered by `Object.keys`, so define the record in the canonical
2243
+ * `Confirmed → Packed → Shipped → Delivered` order.
1881
2244
  */
1882
- fulfilmentDetails: Record<FulfilmentStage, FulfilmentStageDetail>;
1883
- /** Override price formatting (locale, currency). Defaults to USD. */
1884
- formatPrice?: (value: number) => string;
2245
+ fulfilmentDetails?: Record<FulfilmentStage, FulfilmentStageDetail>;
2246
+ /** Override money formatting (locale, currency). Defaults to `Money.currencyCode`. */
2247
+ formatPrice?: (money: Money) => string;
1885
2248
  titleLabel?: string;
1886
2249
  /** Template with `{number}`/`{date}`/`{email}` placeholders, resolved internally. */
1887
2250
  orderPlacedLabel?: string;
2251
+ /** Used when the order carries no email. */
2252
+ orderPlacedNoEmailLabel?: string;
1888
2253
  itemsLabel?: string;
1889
2254
  quantityLabel?: string;
1890
2255
  subtotalLabel?: string;
2256
+ discountLabel?: string;
1891
2257
  shippingLabel?: string;
1892
2258
  taxLabel?: string;
1893
2259
  totalLabel?: string;
1894
2260
  freeLabel?: string;
2261
+ /** Shown for a line whose supplied line total is absent or malformed. */
2262
+ amountUnavailableLabel?: string;
1895
2263
  shippingAddressLabel?: string;
1896
2264
  billingAddressLabel?: string;
1897
2265
  continueShoppingLabel?: string;
@@ -1918,7 +2286,7 @@ interface CheckoutConfirmationProps {
1918
2286
  * your order record. Only the progress tabs are interactive, and they carry their own
1919
2287
  * `'use client'` — the boundary is one child rather than the whole page.
1920
2288
  */
1921
- declare function CheckoutConfirmation({ order, orderLines, fulfilmentDetails, formatPrice, titleLabel, orderPlacedLabel, itemsLabel, quantityLabel, subtotalLabel, shippingLabel, taxLabel, totalLabel, freeLabel, shippingAddressLabel, billingAddressLabel, continueShoppingLabel, contactSupportLabel, supportLabel, progressLabel, estimatedDeliveryLabel, currentStageLabel, inProgressLabel, expectedByLabel, completedLabel, statusLabel, locationLabel, trackOrderLabel, continueShoppingHref, supportHref, onContinueShopping, }: CheckoutConfirmationProps): react.JSX.Element;
2289
+ declare function CheckoutConfirmation({ order, orderLines, fulfilmentDetails, formatPrice, titleLabel, orderPlacedLabel, orderPlacedNoEmailLabel, itemsLabel, quantityLabel, subtotalLabel, discountLabel, shippingLabel, taxLabel, totalLabel, freeLabel, amountUnavailableLabel, shippingAddressLabel, billingAddressLabel, continueShoppingLabel, contactSupportLabel, supportLabel, progressLabel, estimatedDeliveryLabel, currentStageLabel, inProgressLabel, expectedByLabel, completedLabel, statusLabel, locationLabel, trackOrderLabel, continueShoppingHref, supportHref, onContinueShopping, }: CheckoutConfirmationProps): react.JSX.Element;
1922
2290
 
1923
2291
  interface OrderHistory1Order {
1924
2292
  name: string;
@@ -1994,6 +2362,10 @@ interface FeaturedProduct$1 {
1994
2362
  image: string;
1995
2363
  colors: string[];
1996
2364
  }
2365
+ interface HeroImage {
2366
+ src: string;
2367
+ alt: string;
2368
+ }
1997
2369
  interface StorefrontHero1Props {
1998
2370
  title: string;
1999
2371
  description: string;
@@ -2002,6 +2374,12 @@ interface StorefrontHero1Props {
2002
2374
  badge?: string;
2003
2375
  primaryCta?: CTA;
2004
2376
  secondaryCta?: CTA;
2377
+ /**
2378
+ * Optional editorial image. Rendered as a native `<img>` when `src` is a
2379
+ * non-empty string; omitted entirely when absent or blank (never an empty
2380
+ * `src`). The product grid is unaffected.
2381
+ */
2382
+ heroImage?: HeroImage;
2005
2383
  onAddToCart?: (product: FeaturedProduct$1) => void;
2006
2384
  onBuyNow?: (product: FeaturedProduct$1) => void;
2007
2385
  onSelectColor?: (product: FeaturedProduct$1, index: number, color: string) => void;
@@ -2011,7 +2389,7 @@ interface StorefrontHero1Props {
2011
2389
  outOfStockLabel?: string;
2012
2390
  colorsLabel?: string;
2013
2391
  }
2014
- declare function StorefrontHero1({ title, description, products, titleAccent, badge, primaryCta, secondaryCta, onAddToCart, onBuyNow, onSelectColor, addToCartLabel, buyNowLabel, newLabel, outOfStockLabel, colorsLabel, }: StorefrontHero1Props): react.JSX.Element;
2392
+ declare function StorefrontHero1({ title, description, products, titleAccent, badge, primaryCta, secondaryCta, heroImage, onAddToCart, onBuyNow, onSelectColor, addToCartLabel, buyNowLabel, newLabel, outOfStockLabel, colorsLabel, }: StorefrontHero1Props): react.JSX.Element;
2015
2393
 
2016
2394
  interface FeaturedProduct {
2017
2395
  /** Unique identifier for the product. */
@@ -2405,4 +2783,4 @@ interface Verify1Props {
2405
2783
  }
2406
2784
  declare function Verify1({ verifyTitleLabel, verifyDescriptionLabel, backupCodeTitleLabel, backupCodeDescriptionLabel, backupCodeLabel, backupCodePlaceholder, otpAriaLabel, verifyLabel, resendCodeLabel, resendCooldownLabel, useBackupCodeLabel, useAuthenticatorLabel, tooManyAttemptsLabel, attemptsLeftLabel, verifiedTitleLabel, verifiedDescriptionLabel, continueLabel, demoOtpHintLabel, demoBackupHintLabel, onVerify, onVerifyBackup, onResend, onContinue, }: Verify1Props): react.JSX.Element;
2407
2785
 
2408
- export { AppShell1, Avatar, AvatarFallback, AvatarImage, Badge, Banner1, Button, type CTA, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CategoryFilter1, CategoryFilter2, type CategoryFilter2Category, type CategoryFilter2Color, type CategoryFilter2Filters, type CategoryFilter2PriceRange, type CategoryFilter2Props, type CategoryFilter2SortOption, CategoryFilter4, type CategoryFilter4Facets, type CategoryFilter4Product, type CategoryFilter4Props, CategoryIcon, type CategoryIconName, type CategoryIconProps, CheckoutConfirmation, type CheckoutConfirmationProps, type CheckoutFieldError, type CheckoutFieldErrors, CheckoutForm1, type CheckoutForm1ChangeHandler, type CheckoutForm1CountryOption, type CheckoutForm1FieldDescriptions, type CheckoutForm1FieldErrors, type CheckoutForm1FormData, type CheckoutForm1OrderSummary, type CheckoutForm1OrderSummaryItem, type CheckoutForm1Props, CheckoutForm2, type CheckoutForm2Data, type CheckoutForm2FieldDescriptions, type CheckoutForm2FieldErrors, type CheckoutForm2Item, type CheckoutForm2Props, type CheckoutForm2Totals, CheckoutForm3, type CheckoutForm3CartItem, type CheckoutForm3CountryOption, type CheckoutForm3FormData, type CheckoutForm3Props, type CheckoutForm3ShippingMethod, type CollectionItem, CtaSection1, type CtaSection1Props, FaqBlock1, type FaqBlock1Props, type FaqItem, Feature1, type Feature1Item, type Feature1Props, Feature2, type Feature2Item, type Feature2Props, type FeaturedProduct$1 as FeaturedProduct, type FilterProduct, type FooterLink, type FooterLinkColumn, FooterSection1, FooterSection3, type FooterSection3Props, FooterSection4, type FooterSection4Contact, type FooterSection4Link, type FooterSection4LinkColumn, type FooterSection4Props, type FooterSection4SocialIcon, type FooterSection4SocialLink, ForgotPasswordPage1, type ForgotPasswordPage1Props, type FulfilmentStage, type FulfilmentStageDetail, HeroSection1, LoginPage1, type LoginPage1FormData, type LoginPage1Props, type LoginPage1SocialButton, LoginPage2, type LoginPage2Props, type LoginPage2SocialButton, LogoCloud1, type LogoCloud1Platform, type LogoCloud1Props, MegaMenu, type MegaMenuProps, type MenuItem, MobileCategoryDrawer, type MobileCategoryDrawerProps, Navbar1, Navbar2, Navbar3, Navbar4, type Order$1 as Order, type OrderAddress, OrderHistory1, OrderHistory2, type OrderLine, type OrderTotals, PricingSection1, type PricingSection1Props, type PricingTier, ProductCard1, ProductCard2, ProductCard3, ProductCard5, ProductCategory1, type ProductCategory1Category, type ProductCategory1CategoryIcon, type ProductCategory1Props, ProductCategory2, type ProductCategory2Category, type ProductCategory2Props, ProductCategory4, ProductCategory5, ProductOverview1, ProductOverview2, type ProductOverview2Product, type ProductOverview2Props, ProductOverview5, type ProductOverview5Product, type ProductOverview5Props, type ProductOverview5Review, ProductQuickView, ReviewRating1, type ReviewRating1Review, ReviewRating2, ShoppingCart1, ShoppingCart2, type ShoppingCart2Item, type ShoppingCart2Props, ShoppingCart3, type ShoppingCart3CartItem, type ShoppingCart3Props, ShoppingCart4, type ShoppingCart4Item, type ShoppingCart4Props, SignUpPage1, type SignUpPage1Data, type SignUpPage1Props, type SignUpPage1SocialButton, type SocialLink, Statistic1, type Statistic1Props, type StatisticItem, StoreCategory, StoreContainer1, type StoreContainer1Props, StorefrontHero1, type StorefrontHero1Props, StorefrontHero2, StorefrontHero5, StorefrontHero6, Testimonial1, type Testimonial1Item, type Testimonial1Props, Testimonial2, type Testimonial2Item, type Testimonial2Props, Verify1, type Verify1Props, badgeVariants, buttonVariants, categoryIconNameSchema, categoryIconPropsSchema, cn, collectionItemSchema, megaMenuPropsSchema, menuItemSchema, mobileCategoryDrawerPropsSchema };
2786
+ export { AppShell1, Avatar, AvatarFallback, AvatarImage, Badge, Banner1, Button, type CTA, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CategoryFilter1, type CategoryFilter1Category, type CategoryFilter1PriceRange, type CategoryFilter1SortOption, CategoryFilter2, type CategoryFilter2ActiveFilter, type CategoryFilter2ActiveFilterKind, type CategoryFilter2Category, type CategoryFilter2Collection, type CategoryFilter2Color, type CategoryFilter2Filters, type CategoryFilter2PriceRange, type CategoryFilter2Props, type CategoryFilter2QueryError, type CategoryFilter2SortOption, type CategoryFilter2Status, CategoryFilter2StatusView, type CategoryFilter2StatusViewProps, CategoryFilter4, type CategoryFilter4Facets, type CategoryFilter4Product, type CategoryFilter4Props, CategoryIcon, type CategoryIconName, type CategoryIconProps, CheckoutConfirmation, type CheckoutConfirmationProps, type CheckoutFieldError, type CheckoutFieldErrors, CheckoutForm1, type CheckoutForm1ChangeHandler, type CheckoutForm1CountryOption, type CheckoutForm1FieldDescriptions, type CheckoutForm1FieldErrors, type CheckoutForm1FormData, type CheckoutForm1OrderSummary, type CheckoutForm1OrderSummaryItem, type CheckoutForm1Props, type CheckoutForm1ShippingOption, type CheckoutForm1Totals, type CheckoutForm1TotalsState, CheckoutForm2, type CheckoutForm2Data, type CheckoutForm2FieldDescriptions, type CheckoutForm2FieldErrors, type CheckoutForm2Item, type CheckoutForm2Props, type CheckoutForm2Totals, CheckoutForm3, type CheckoutForm3CartItem, type CheckoutForm3CountryOption, type CheckoutForm3FormData, type CheckoutForm3Props, type CheckoutForm3ShippingMethod, type CollectionItem, CtaSection1, type CtaSection1Props, FaqBlock1, type FaqBlock1Props, type FaqItem, Feature1, type Feature1Item, type Feature1Props, Feature2, type Feature2Item, type Feature2Props, type FeaturedProduct$1 as FeaturedProduct, type FilterProduct, type FooterLink, type FooterLinkColumn, FooterSection1, FooterSection3, type FooterSection3Props, FooterSection4, type FooterSection4Contact, type FooterSection4Link, type FooterSection4LinkColumn, type FooterSection4Props, type FooterSection4SocialIcon, type FooterSection4SocialLink, ForgotPasswordPage1, type ForgotPasswordPage1Props, type FulfilmentStage, type FulfilmentStageDetail, HeroSection1, LoginPage1, type LoginPage1FormData, type LoginPage1Props, type LoginPage1SocialButton, LoginPage2, type LoginPage2Props, type LoginPage2SocialButton, LogoCloud1, type LogoCloud1Platform, type LogoCloud1Props, MegaMenu, type MegaMenuProps, type MenuItem, MobileCategoryDrawer, type MobileCategoryDrawerProps, Navbar1, Navbar2, Navbar3, Navbar4, type Order$1 as Order, type OrderAddress, OrderHistory1, OrderHistory2, type OrderLine, type OrderTotals, PricingSection1, type PricingSection1Props, type PricingTier, ProductCard1, ProductCard2, ProductCard3, ProductCard5, ProductCategory1, type ProductCategory1Category, type ProductCategory1CategoryIcon, type ProductCategory1Props, ProductCategory2, type ProductCategory2Category, type ProductCategory2Props, ProductCategory4, ProductCategory5, type ProductDetailProduct, type ProductDetailVariant, ProductOverview1, type ProductOverview1Props, type ProductOverview1Rating, ProductOverview2, type ProductOverview2Product, type ProductOverview2Props, ProductOverview5, type ProductOverview5Product, type ProductOverview5Props, type ProductOverview5Review, ProductQuickView, ReviewRating1, type ReviewRating1Review, ReviewRating2, ShoppingCart1, ShoppingCart2, type ShoppingCart2Item, type ShoppingCart2Props, ShoppingCart3, type ShoppingCart3CartItem, type ShoppingCart3Props, ShoppingCart4, type ShoppingCart4Item, type ShoppingCart4Props, SignUpPage1, type SignUpPage1Data, type SignUpPage1Props, type SignUpPage1SocialButton, type SocialLink, Statistic1, type Statistic1Props, type StatisticItem, StoreCategory, StoreContainer1, type StoreContainer1Props, StorefrontHero1, type StorefrontHero1Props, StorefrontHero2, StorefrontHero5, StorefrontHero6, Testimonial1, type Testimonial1Item, type Testimonial1Props, Testimonial2, type Testimonial2Item, type Testimonial2Props, Verify1, type Verify1Props, badgeVariants, buttonVariants, categoryIconNameSchema, categoryIconPropsSchema, cn, collectionItemSchema, megaMenuPropsSchema, menuItemSchema, mobileCategoryDrawerPropsSchema };