@godaddy/gd-commerce-storefront 0.9.0 → 0.11.0
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.
- package/README.md +100 -9
- package/dist/index.d.ts +256 -163
- package/dist/index.js +756 -249
- package/dist/messages/fr-FR.d.ts +7 -0
- package/dist/messages/fr-FR.js +143 -0
- package/dist/messages-CHl-bWx9.d.ts +152 -0
- package/dist/styles.css +6 -0
- package/package.json +13 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { a as StorefrontMessages, i as StorefrontMessageKey, n as MessageValues, o as enUS, r as StorefrontMessage, s as formatMessage, t as CommerceErrorCode } from "./messages-CHl-bWx9.js";
|
|
1
2
|
import { CSSProperties, ReactElement, ReactNode } from "react";
|
|
2
3
|
import * as react_jsx_runtime0 from "react/jsx-runtime";
|
|
3
4
|
|
|
@@ -11,10 +12,25 @@ interface StorefrontConfig {
|
|
|
11
12
|
}
|
|
12
13
|
declare class ApiError extends Error {
|
|
13
14
|
readonly status: number;
|
|
14
|
-
|
|
15
|
+
/** The failure response's `code`, such as `not_found`, when the server sent one. */
|
|
16
|
+
readonly code: string | undefined;
|
|
17
|
+
/** Package text to show in place of `message`, for failures the package describes itself. */
|
|
18
|
+
readonly text: {
|
|
19
|
+
key: StorefrontMessageKey;
|
|
20
|
+
values?: MessageValues;
|
|
21
|
+
} | undefined;
|
|
22
|
+
constructor(message: string, status: number, options?: ErrorOptions & {
|
|
23
|
+
code?: string;
|
|
24
|
+
text?: {
|
|
25
|
+
key: StorefrontMessageKey;
|
|
26
|
+
values?: MessageValues;
|
|
27
|
+
};
|
|
28
|
+
});
|
|
15
29
|
}
|
|
16
30
|
/** Formats minor units, such as cents, as currency. Inside the provider, prefer `useMoney`, which follows its `locale`. */
|
|
17
31
|
declare function money(value: number, currency: string, locale?: string): string;
|
|
32
|
+
/** Formats a range of minor units the way `locale` writes ranges, such as `$20.00 – $25.00` or `20,00–25,00 €`. */
|
|
33
|
+
declare function moneyRange(min: number, max: number, currency: string, locale?: string): string;
|
|
18
34
|
//#endregion
|
|
19
35
|
//#region src/cart-model.d.ts
|
|
20
36
|
interface Money {
|
|
@@ -150,7 +166,8 @@ interface CartSummaryTotals {
|
|
|
150
166
|
declare function addToCart(cartId: string | null, item: AddToCartItemInput, fetchFn?: typeof globalThis.fetch): Promise<{
|
|
151
167
|
cart: CartOrder | null;
|
|
152
168
|
}>;
|
|
153
|
-
|
|
169
|
+
/** The cart's totals in minor units. `currencyCode` is the cart's, or `fallbackCurrency`, such as the store's. */
|
|
170
|
+
declare function getCartSummaryTotals(order: CartOrder | null | undefined, fallbackCurrency?: string): CartSummaryTotals;
|
|
154
171
|
//#endregion
|
|
155
172
|
//#region src/catalog-model.d.ts
|
|
156
173
|
interface PageInfo {
|
|
@@ -359,9 +376,192 @@ interface AddToCartButtonProps {
|
|
|
359
376
|
}
|
|
360
377
|
declare function AddToCartButton(props: AddToCartButtonProps): ReactElement;
|
|
361
378
|
//#endregion
|
|
379
|
+
//#region src/commerce-provider.d.ts
|
|
380
|
+
interface CommerceContextValue {
|
|
381
|
+
connection: 'loading' | 'unbound' | 'connecting' | 'ready' | 'error';
|
|
382
|
+
connectionError: string | null;
|
|
383
|
+
retryConnection: () => void;
|
|
384
|
+
theme: StorefrontTheme;
|
|
385
|
+
/** The host's swatch lookup, or `undefined` when options render as buttons. */
|
|
386
|
+
getSwatch: GetSwatch | undefined;
|
|
387
|
+
config: StorefrontConfig;
|
|
388
|
+
/** The BCP 47 locale that prices are formatted in, such as `en-US`. */
|
|
389
|
+
locale: string;
|
|
390
|
+
/** The package's text: English, with the provider's `messages` over it. */
|
|
391
|
+
messages: StorefrontMessages;
|
|
392
|
+
cart: CartOrder | null;
|
|
393
|
+
/** Whether the cart drawer is open. Always `false` when no `CartDrawer` or `CartDrawerRoot` is mounted. */
|
|
394
|
+
open: boolean;
|
|
395
|
+
/** Opens or closes the cart drawer. Opening does nothing without a mounted drawer. */
|
|
396
|
+
setOpen: (open: boolean) => void;
|
|
397
|
+
/** Restores the initiating control after the cart drawer closes. */
|
|
398
|
+
restoreFocus: () => void;
|
|
399
|
+
pending: boolean;
|
|
400
|
+
hydrating: boolean;
|
|
401
|
+
error: string | null;
|
|
402
|
+
storageWarning: string | null;
|
|
403
|
+
announcement: string;
|
|
404
|
+
addItem: (item: AddToCartItemInput) => Promise<boolean>;
|
|
405
|
+
changeQuantity: (itemId: string, quantity: number) => Promise<boolean>;
|
|
406
|
+
removeItem: (itemId: string) => Promise<boolean>;
|
|
407
|
+
applyDiscount: (code: string) => Promise<boolean>;
|
|
408
|
+
refresh: () => Promise<boolean>;
|
|
409
|
+
checkout: () => Promise<boolean>;
|
|
410
|
+
}
|
|
411
|
+
declare function useCommerce(): CommerceContextValue;
|
|
412
|
+
/**
|
|
413
|
+
* Formats minor units, such as cents, in the provider's `locale`, the way the package's own parts do. Uses the
|
|
414
|
+
* store's currency unless `currency` is given.
|
|
415
|
+
*/
|
|
416
|
+
declare function useMoney(): (value: number, currency?: string) => string;
|
|
417
|
+
/** `useMoney` for a range, such as `$20.00 – $25.00`, written the way the provider's `locale` writes ranges. */
|
|
418
|
+
declare function useMoneyRange(): (min: number, max: number, currency?: string) => string;
|
|
419
|
+
/**
|
|
420
|
+
* The provider's text for `key`, with `{placeholders}` filled from `values`, the way the package's own parts read
|
|
421
|
+
* it. For custom parts that should match the package's language. English outside a provider.
|
|
422
|
+
*/
|
|
423
|
+
declare function useMessage(): (key: StorefrontMessageKey, values?: MessageValues) => string;
|
|
424
|
+
type StorefrontTheme = CSSProperties & {
|
|
425
|
+
'--commerce-accent'?: string;
|
|
426
|
+
'--commerce-accent-hover'?: string;
|
|
427
|
+
'--commerce-on-accent'?: string;
|
|
428
|
+
'--commerce-surface'?: string;
|
|
429
|
+
'--commerce-text'?: string;
|
|
430
|
+
'--commerce-radius'?: string;
|
|
431
|
+
/** Fills the Sale badge. Defaults to a red that white text reads on. */
|
|
432
|
+
'--commerce-sale'?: string;
|
|
433
|
+
/** Text on the Sale badge. Defaults to white. */
|
|
434
|
+
'--commerce-on-sale'?: string;
|
|
435
|
+
/**
|
|
436
|
+
* The aspect ratio of catalog card images and their loading placeholders, such as `3 / 4`. Defaults to `1 / 1`.
|
|
437
|
+
* Can also be set on a card or any element around it.
|
|
438
|
+
*/
|
|
439
|
+
'--commerce-card-image-aspect'?: string;
|
|
440
|
+
};
|
|
441
|
+
/** The attribute value a host can give a swatch, such as `{ attribute: 'color', name: 'forest', label: 'Forest' }`. */
|
|
442
|
+
interface SwatchValue {
|
|
443
|
+
readonly attribute: string;
|
|
444
|
+
readonly name: string;
|
|
445
|
+
readonly label: string;
|
|
446
|
+
}
|
|
447
|
+
/**
|
|
448
|
+
* Returns a CSS `background` for a value, such as `'#3f6352'` or `'url(/swatches/linen.png) center / cover'`, or
|
|
449
|
+
* nothing for no swatch. An attribute shows swatches only when every value has one.
|
|
450
|
+
*/
|
|
451
|
+
type GetSwatch = (value: SwatchValue) => string | null | undefined;
|
|
452
|
+
interface CommerceProviderProps {
|
|
453
|
+
children: ReactNode;
|
|
454
|
+
catalogPath?: string;
|
|
455
|
+
productPath?: string;
|
|
456
|
+
/** Applied to storefront surfaces and the portalled cart drawer. */
|
|
457
|
+
theme?: StorefrontTheme;
|
|
458
|
+
/**
|
|
459
|
+
* Swatches for attribute values, off by default. Attributes whose values all have a swatch render as swatches on
|
|
460
|
+
* the product page, and cards show them as dots. See `GetSwatch`.
|
|
461
|
+
*/
|
|
462
|
+
getSwatch?: GetSwatch;
|
|
463
|
+
/** Set only when your server has enabled checkout and this return route exists. */
|
|
464
|
+
checkoutSuccessPath?: string;
|
|
465
|
+
/**
|
|
466
|
+
* The BCP 47 locale for formatting prices, such as `de-DE`. Defaults to `en-US`; an invalid tag falls back to it.
|
|
467
|
+
* It never selects UI text; set `messages` for that.
|
|
468
|
+
*/
|
|
469
|
+
locale?: string;
|
|
470
|
+
/**
|
|
471
|
+
* The package's text, such as `frFR` from `@godaddy/gd-commerce-storefront/messages/fr-FR`. Keys left out use
|
|
472
|
+
* English. Independent of `locale`, so set both for a translated store. Part `children` and props such as
|
|
473
|
+
* `CatalogHeader`'s `title` still replace the text where given.
|
|
474
|
+
*/
|
|
475
|
+
messages?: Partial<StorefrontMessages>;
|
|
476
|
+
/**
|
|
477
|
+
* Called after an item is added, live or sample. With a drawer mounted, the drawer also opens. Without one, such as
|
|
478
|
+
* on a site with a cart page, use it to confirm the add.
|
|
479
|
+
*/
|
|
480
|
+
onItemAdded?: (item: AddedCartItem) => void;
|
|
481
|
+
/** Called for every cart change and failure, such as for analytics. See `CommerceEvent`. */
|
|
482
|
+
onEvent?: (event: CommerceEvent) => void;
|
|
483
|
+
}
|
|
484
|
+
/** A cart operation that can fail. */
|
|
485
|
+
type CommerceOperation = 'add' | 'change-quantity' | 'remove' | 'discount' | 'refresh' | 'checkout';
|
|
486
|
+
/**
|
|
487
|
+
* What `onEvent` reports. Live changes are reported once the server returns the updated cart; sample changes have
|
|
488
|
+
* `isSample: true` and never reach the store. New event types may be added, so ignore types you do not handle.
|
|
489
|
+
*/
|
|
490
|
+
type CommerceEvent = {
|
|
491
|
+
readonly type: 'item-added';
|
|
492
|
+
/** `null` for a sample product, which is not a SKU. */
|
|
493
|
+
readonly skuId: string | null;
|
|
494
|
+
readonly name: string;
|
|
495
|
+
readonly quantity: number;
|
|
496
|
+
readonly isSample: boolean;
|
|
497
|
+
} | {
|
|
498
|
+
readonly type: 'quantity-changed';
|
|
499
|
+
readonly itemId: string;
|
|
500
|
+
readonly quantity: number;
|
|
501
|
+
readonly isSample: boolean;
|
|
502
|
+
} | {
|
|
503
|
+
readonly type: 'item-removed';
|
|
504
|
+
readonly itemId: string;
|
|
505
|
+
readonly isSample: boolean;
|
|
506
|
+
} | {
|
|
507
|
+
readonly type: 'discount-applied';
|
|
508
|
+
readonly code: string;
|
|
509
|
+
}
|
|
510
|
+
/** Sent just before the browser leaves for checkout. */ | {
|
|
511
|
+
readonly type: 'checkout-started';
|
|
512
|
+
readonly cartId: string;
|
|
513
|
+
}
|
|
514
|
+
/**
|
|
515
|
+
* `message` is the one the cart shows, in the provider's language. `code` is the server's failure code, such as
|
|
516
|
+
* `scope_mismatch`, when it sent one.
|
|
517
|
+
*/ | {
|
|
518
|
+
readonly type: 'error';
|
|
519
|
+
readonly operation: CommerceOperation;
|
|
520
|
+
readonly message: string;
|
|
521
|
+
readonly code?: string;
|
|
522
|
+
};
|
|
523
|
+
/** The item passed to `onItemAdded`. */
|
|
524
|
+
interface AddedCartItem {
|
|
525
|
+
readonly name: string;
|
|
526
|
+
readonly quantity: number;
|
|
527
|
+
/** `true` for the sample cart, before a store is connected. */
|
|
528
|
+
readonly isSample: boolean;
|
|
529
|
+
}
|
|
530
|
+
declare function CommerceProvider({
|
|
531
|
+
children,
|
|
532
|
+
catalogPath,
|
|
533
|
+
productPath,
|
|
534
|
+
checkoutSuccessPath,
|
|
535
|
+
theme,
|
|
536
|
+
getSwatch,
|
|
537
|
+
locale,
|
|
538
|
+
messages,
|
|
539
|
+
onItemAdded,
|
|
540
|
+
onEvent
|
|
541
|
+
}: CommerceProviderProps): ReactElement;
|
|
542
|
+
//#endregion
|
|
543
|
+
//#region src/sample-cart.d.ts
|
|
544
|
+
/**
|
|
545
|
+
* A product to show while no store is connected. Deliberately distinct from SKU groups, SKUs and draft orders: it
|
|
546
|
+
* is never sent to Commerce. Add any fields of your own, such as a category, and read them back from `sample` in
|
|
547
|
+
* `useProductCard()` and `useCartItem()`.
|
|
548
|
+
*/
|
|
549
|
+
interface SampleProduct {
|
|
550
|
+
/** Unique among the site's samples. `sample-1` to `sample-6` are the packaged samples' keys. */
|
|
551
|
+
readonly key: string;
|
|
552
|
+
readonly name: string;
|
|
553
|
+
/** In minor units of `sampleCurrency`, such as 3200 for $32.00. */
|
|
554
|
+
readonly price: number;
|
|
555
|
+
/** A higher earlier price, in minor units. The card then shows the sale badge and the struck-through price. */
|
|
556
|
+
readonly compareAtPrice?: number;
|
|
557
|
+
readonly description?: string;
|
|
558
|
+
/** Any URL the browser can load, such as a file in the site's own public folder. */
|
|
559
|
+
readonly imageUrl?: string;
|
|
560
|
+
}
|
|
561
|
+
//#endregion
|
|
362
562
|
//#region src/cart-state.d.ts
|
|
363
563
|
/** One cart line, for custom cart parts. */
|
|
364
|
-
interface CartItemState {
|
|
564
|
+
interface CartItemState<Sample extends SampleProduct = SampleProduct> {
|
|
365
565
|
/** Empty when the server returned a line without an ID. Such a line cannot be changed or removed. */
|
|
366
566
|
readonly id: string;
|
|
367
567
|
readonly name: string;
|
|
@@ -374,6 +574,8 @@ interface CartItemState {
|
|
|
374
574
|
/** The line total in minor units, or `null` when the server did not price it. */
|
|
375
575
|
readonly subtotal: number | null;
|
|
376
576
|
readonly currency: string;
|
|
577
|
+
/** The sample as it was added, with the site's own fields. `null` for a line in the connected store's cart. */
|
|
578
|
+
readonly sample: Sample | null;
|
|
377
579
|
}
|
|
378
580
|
/** Read-only cart contents: the connected store's cart, or the sample cart while no store is connected. */
|
|
379
581
|
interface CartState {
|
|
@@ -456,8 +658,12 @@ declare function CartClose({
|
|
|
456
658
|
declare function CartNotices({
|
|
457
659
|
className
|
|
458
660
|
}: CartPartProps): ReactElement | null;
|
|
459
|
-
/**
|
|
460
|
-
|
|
661
|
+
/**
|
|
662
|
+
* Read the line from inside `CartItemRoot`, for custom item parts. Pass the type of the site's samples, such as
|
|
663
|
+
* `useCartItem<MySample>()`, to read their own fields from `sample`. The type is not checked: when the cart can hold
|
|
664
|
+
* samples from more than one catalog, read the site's own fields as possibly missing.
|
|
665
|
+
*/
|
|
666
|
+
declare function useCartItem<Sample extends SampleProduct = SampleProduct>(): CartItemState<Sample>;
|
|
461
667
|
interface CartItemsProps extends CartPartProps {
|
|
462
668
|
/** One item, rendered for every cart line. Defaults to the packaged item. */
|
|
463
669
|
children?: ReactNode;
|
|
@@ -557,13 +763,29 @@ declare function CartDrawer(): ReactElement;
|
|
|
557
763
|
interface CatalogPartProps {
|
|
558
764
|
className?: string;
|
|
559
765
|
}
|
|
766
|
+
/** Read-only catalog state for custom catalog parts rendered inside `CatalogRoot`. */
|
|
767
|
+
interface CatalogState {
|
|
768
|
+
/**
|
|
769
|
+
* Products on the current page: `0` while loading or after a first load fails. A failed refetch keeps the last page,
|
|
770
|
+
* so `status` can be `error` while `count` is above `0`.
|
|
771
|
+
*/
|
|
772
|
+
readonly count: number;
|
|
773
|
+
readonly isSample: boolean;
|
|
774
|
+
/** Samples are always `ready`. */
|
|
775
|
+
readonly status: 'loading' | 'error' | 'ready';
|
|
776
|
+
}
|
|
777
|
+
/** Read how many products the catalog shows, and whether they are samples, for a custom summary. */
|
|
778
|
+
declare function useCatalog(): CatalogState;
|
|
560
779
|
interface CatalogRootProps {
|
|
561
780
|
children: ReactNode;
|
|
562
781
|
/** Added to the root `<section>`. */
|
|
563
782
|
className?: string;
|
|
564
|
-
/**
|
|
565
|
-
|
|
566
|
-
|
|
783
|
+
/**
|
|
784
|
+
* Products to show only while the server reports no connected store (`unbound`): `true` for the six packaged
|
|
785
|
+
* samples, or the site's own. Never shown once a store is connected. Defaults to `false`.
|
|
786
|
+
*/
|
|
787
|
+
sampleProducts?: boolean | readonly SampleProduct[];
|
|
788
|
+
/** Products per page, a whole number of 1 or more. Defaults to 6. Samples are always one page. */
|
|
567
789
|
pageSize?: number;
|
|
568
790
|
/**
|
|
569
791
|
* Keep the page cursor in the page URL, as `after`, so a reload or a shared link keeps the page. Defaults to
|
|
@@ -571,7 +793,7 @@ interface CatalogRootProps {
|
|
|
571
793
|
*/
|
|
572
794
|
urlState?: boolean;
|
|
573
795
|
}
|
|
574
|
-
/** Loads one cursor page of products, or the
|
|
796
|
+
/** Loads one cursor page of products, or the samples, and provides them to catalog parts. */
|
|
575
797
|
declare function CatalogRoot({
|
|
576
798
|
children,
|
|
577
799
|
className,
|
|
@@ -580,8 +802,10 @@ declare function CatalogRoot({
|
|
|
580
802
|
urlState
|
|
581
803
|
}: CatalogRootProps): ReactElement;
|
|
582
804
|
interface CatalogHeaderProps extends CatalogPartProps {
|
|
583
|
-
|
|
584
|
-
|
|
805
|
+
/** Defaults to the provider's `catalogTitle` message. `null` leaves the heading out. */
|
|
806
|
+
title?: string | null;
|
|
807
|
+
/** Defaults to the provider's `catalogDescription` message. `null` leaves it out. */
|
|
808
|
+
description?: string | null;
|
|
585
809
|
}
|
|
586
810
|
/** The catalog title as the page's H1, with a description. */
|
|
587
811
|
declare function CatalogHeader({
|
|
@@ -630,8 +854,8 @@ interface CatalogProps {
|
|
|
630
854
|
description?: string;
|
|
631
855
|
/** @deprecated To render the page's own H1, compose `CatalogRoot` without `CatalogHeader` instead. */
|
|
632
856
|
showHeader?: boolean;
|
|
633
|
-
/**
|
|
634
|
-
sampleProducts?: boolean;
|
|
857
|
+
/** Products to show only while no store is connected, as in `CatalogRoot`. */
|
|
858
|
+
sampleProducts?: boolean | readonly SampleProduct[];
|
|
635
859
|
/** Products per page. Defaults to 6. */
|
|
636
860
|
pageSize?: number;
|
|
637
861
|
}
|
|
@@ -644,145 +868,6 @@ declare function Catalog({
|
|
|
644
868
|
pageSize
|
|
645
869
|
}: CatalogProps): ReactElement;
|
|
646
870
|
//#endregion
|
|
647
|
-
//#region src/commerce-provider.d.ts
|
|
648
|
-
interface CommerceContextValue {
|
|
649
|
-
connection: 'loading' | 'unbound' | 'connecting' | 'ready' | 'error';
|
|
650
|
-
connectionError: string | null;
|
|
651
|
-
retryConnection: () => void;
|
|
652
|
-
theme: StorefrontTheme;
|
|
653
|
-
/** The host's swatch lookup, or `undefined` when options render as buttons. */
|
|
654
|
-
getSwatch: GetSwatch | undefined;
|
|
655
|
-
config: StorefrontConfig;
|
|
656
|
-
/** The BCP 47 locale that prices are formatted in, such as `en-US`. */
|
|
657
|
-
locale: string;
|
|
658
|
-
cart: CartOrder | null;
|
|
659
|
-
/** Whether the cart drawer is open. Always `false` when no `CartDrawer` or `CartDrawerRoot` is mounted. */
|
|
660
|
-
open: boolean;
|
|
661
|
-
/** Opens or closes the cart drawer. Opening does nothing without a mounted drawer. */
|
|
662
|
-
setOpen: (open: boolean) => void;
|
|
663
|
-
/** Restores the initiating control after the cart drawer closes. */
|
|
664
|
-
restoreFocus: () => void;
|
|
665
|
-
pending: boolean;
|
|
666
|
-
hydrating: boolean;
|
|
667
|
-
error: string | null;
|
|
668
|
-
storageWarning: string | null;
|
|
669
|
-
announcement: string;
|
|
670
|
-
addItem: (item: AddToCartItemInput) => Promise<boolean>;
|
|
671
|
-
changeQuantity: (itemId: string, quantity: number) => Promise<boolean>;
|
|
672
|
-
removeItem: (itemId: string) => Promise<boolean>;
|
|
673
|
-
applyDiscount: (code: string) => Promise<boolean>;
|
|
674
|
-
refresh: () => Promise<boolean>;
|
|
675
|
-
checkout: () => Promise<boolean>;
|
|
676
|
-
}
|
|
677
|
-
declare function useCommerce(): CommerceContextValue;
|
|
678
|
-
/**
|
|
679
|
-
* Formats minor units, such as cents, in the provider's `locale`, the way the package's own parts do. Uses the
|
|
680
|
-
* store's currency unless `currency` is given.
|
|
681
|
-
*/
|
|
682
|
-
declare function useMoney(): (value: number, currency?: string) => string;
|
|
683
|
-
type StorefrontTheme = CSSProperties & {
|
|
684
|
-
'--commerce-accent'?: string;
|
|
685
|
-
'--commerce-accent-hover'?: string;
|
|
686
|
-
'--commerce-on-accent'?: string;
|
|
687
|
-
'--commerce-surface'?: string;
|
|
688
|
-
'--commerce-text'?: string;
|
|
689
|
-
'--commerce-radius'?: string;
|
|
690
|
-
/** Fills the Sale badge. Defaults to a red that white text reads on. */
|
|
691
|
-
'--commerce-sale'?: string;
|
|
692
|
-
/** Text on the Sale badge. Defaults to white. */
|
|
693
|
-
'--commerce-on-sale'?: string;
|
|
694
|
-
};
|
|
695
|
-
/** The attribute value a host can give a swatch, such as `{ attribute: 'color', name: 'forest', label: 'Forest' }`. */
|
|
696
|
-
interface SwatchValue {
|
|
697
|
-
readonly attribute: string;
|
|
698
|
-
readonly name: string;
|
|
699
|
-
readonly label: string;
|
|
700
|
-
}
|
|
701
|
-
/**
|
|
702
|
-
* Returns a CSS `background` for a value, such as `'#3f6352'` or `'url(/swatches/linen.png) center / cover'`, or
|
|
703
|
-
* nothing for no swatch. An attribute shows swatches only when every value has one.
|
|
704
|
-
*/
|
|
705
|
-
type GetSwatch = (value: SwatchValue) => string | null | undefined;
|
|
706
|
-
interface CommerceProviderProps {
|
|
707
|
-
children: ReactNode;
|
|
708
|
-
catalogPath?: string;
|
|
709
|
-
productPath?: string;
|
|
710
|
-
/** Applied to storefront surfaces and the portalled cart drawer. */
|
|
711
|
-
theme?: StorefrontTheme;
|
|
712
|
-
/**
|
|
713
|
-
* Swatches for attribute values, off by default. Attributes whose values all have a swatch render as swatches on
|
|
714
|
-
* the product page, and cards show them as dots. See `GetSwatch`.
|
|
715
|
-
*/
|
|
716
|
-
getSwatch?: GetSwatch;
|
|
717
|
-
/** Set only when your server has enabled checkout and this return route exists. */
|
|
718
|
-
checkoutSuccessPath?: string;
|
|
719
|
-
/**
|
|
720
|
-
* The BCP 47 locale for formatting prices, such as `de-DE`. Defaults to `en-US`; an invalid tag falls back to it.
|
|
721
|
-
* It never selects UI text: localized text will be a separate, opt-in prop, so setting `locale` cannot change wording.
|
|
722
|
-
*/
|
|
723
|
-
locale?: string;
|
|
724
|
-
/**
|
|
725
|
-
* Called after an item is added, live or sample. With a drawer mounted, the drawer also opens. Without one, such as
|
|
726
|
-
* on a site with a cart page, use it to confirm the add.
|
|
727
|
-
*/
|
|
728
|
-
onItemAdded?: (item: AddedCartItem) => void;
|
|
729
|
-
/** Called for every cart change and failure, such as for analytics. See `CommerceEvent`. */
|
|
730
|
-
onEvent?: (event: CommerceEvent) => void;
|
|
731
|
-
}
|
|
732
|
-
/** A cart operation that can fail. */
|
|
733
|
-
type CommerceOperation = 'add' | 'change-quantity' | 'remove' | 'discount' | 'refresh' | 'checkout';
|
|
734
|
-
/**
|
|
735
|
-
* What `onEvent` reports. Live changes are reported once the server returns the updated cart; sample changes have
|
|
736
|
-
* `isSample: true` and never reach the store. New event types may be added, so ignore types you do not handle.
|
|
737
|
-
*/
|
|
738
|
-
type CommerceEvent = {
|
|
739
|
-
readonly type: 'item-added';
|
|
740
|
-
/** `null` for a sample product, which is not a SKU. */
|
|
741
|
-
readonly skuId: string | null;
|
|
742
|
-
readonly name: string;
|
|
743
|
-
readonly quantity: number;
|
|
744
|
-
readonly isSample: boolean;
|
|
745
|
-
} | {
|
|
746
|
-
readonly type: 'quantity-changed';
|
|
747
|
-
readonly itemId: string;
|
|
748
|
-
readonly quantity: number;
|
|
749
|
-
readonly isSample: boolean;
|
|
750
|
-
} | {
|
|
751
|
-
readonly type: 'item-removed';
|
|
752
|
-
readonly itemId: string;
|
|
753
|
-
readonly isSample: boolean;
|
|
754
|
-
} | {
|
|
755
|
-
readonly type: 'discount-applied';
|
|
756
|
-
readonly code: string;
|
|
757
|
-
}
|
|
758
|
-
/** Sent just before the browser leaves for checkout. */ | {
|
|
759
|
-
readonly type: 'checkout-started';
|
|
760
|
-
readonly cartId: string;
|
|
761
|
-
}
|
|
762
|
-
/** `message` is the one the cart shows. */ | {
|
|
763
|
-
readonly type: 'error';
|
|
764
|
-
readonly operation: CommerceOperation;
|
|
765
|
-
readonly message: string;
|
|
766
|
-
};
|
|
767
|
-
/** The item passed to `onItemAdded`. */
|
|
768
|
-
interface AddedCartItem {
|
|
769
|
-
readonly name: string;
|
|
770
|
-
readonly quantity: number;
|
|
771
|
-
/** `true` for the sample cart, before a store is connected. */
|
|
772
|
-
readonly isSample: boolean;
|
|
773
|
-
}
|
|
774
|
-
declare function CommerceProvider({
|
|
775
|
-
children,
|
|
776
|
-
catalogPath,
|
|
777
|
-
productPath,
|
|
778
|
-
checkoutSuccessPath,
|
|
779
|
-
theme,
|
|
780
|
-
getSwatch,
|
|
781
|
-
locale,
|
|
782
|
-
onItemAdded,
|
|
783
|
-
onEvent
|
|
784
|
-
}: CommerceProviderProps): ReactElement;
|
|
785
|
-
//#endregion
|
|
786
871
|
//#region src/commerce-storefront.d.ts
|
|
787
872
|
/** Mount once inside the application's Router and QueryClientProvider. */
|
|
788
873
|
declare function CommerceStorefront({
|
|
@@ -808,9 +893,11 @@ declare function ProductImage({
|
|
|
808
893
|
className
|
|
809
894
|
}: ProductImageProps): ReactElement;
|
|
810
895
|
/** Read-only card state for custom parts rendered inside `ProductCardRoot`. */
|
|
811
|
-
interface ProductCardState {
|
|
812
|
-
/** `null` for a
|
|
896
|
+
interface ProductCardState<Sample extends SampleProduct = SampleProduct> {
|
|
897
|
+
/** `null` for a sample, which is not a catalog product. */
|
|
813
898
|
readonly product: SKUGroup | null;
|
|
899
|
+
/** The sample as the site passed it to `sampleProducts`, with its own fields. `null` for a catalog product. */
|
|
900
|
+
readonly sample: Sample | null;
|
|
814
901
|
readonly name: string;
|
|
815
902
|
/** The product page, or `null` for a sample, which has none. */
|
|
816
903
|
readonly href: string | null;
|
|
@@ -820,8 +907,12 @@ interface ProductCardState {
|
|
|
820
907
|
interface ProductCardPartProps {
|
|
821
908
|
className?: string;
|
|
822
909
|
}
|
|
823
|
-
/**
|
|
824
|
-
|
|
910
|
+
/**
|
|
911
|
+
* Read the card's product or sample, name, and link from inside `ProductCardRoot`. Pass the type of the site's
|
|
912
|
+
* samples, such as `useProductCard<MySample>()`, to read their own fields from `sample`. The type is not checked:
|
|
913
|
+
* on a page that also shows the packaged samples, read the site's own fields as possibly missing.
|
|
914
|
+
*/
|
|
915
|
+
declare function useProductCard<Sample extends SampleProduct = SampleProduct>(): ProductCardState<Sample>;
|
|
825
916
|
interface ProductCardRootProps {
|
|
826
917
|
children: ReactNode;
|
|
827
918
|
/** The catalog product to show. Leave it out inside `CatalogProducts`, which supplies each product. */
|
|
@@ -836,8 +927,9 @@ declare function ProductCardRoot({
|
|
|
836
927
|
className
|
|
837
928
|
}: ProductCardRootProps): ReactElement;
|
|
838
929
|
/**
|
|
839
|
-
* The product's first image, linked to its page.
|
|
840
|
-
* the title is the one link keyboard and screen reader users get
|
|
930
|
+
* The product's first image, linked to its page. A sample shows its `imageUrl`, unlinked, or the packaged samples'
|
|
931
|
+
* placeholder. With a `ProductCardTitle` in the card, the title is the one link keyboard and screen reader users get,
|
|
932
|
+
* and a sample's image is hidden from screen readers so its name is not read twice; without one, the image is exposed.
|
|
841
933
|
*/
|
|
842
934
|
declare function ProductCardImage({
|
|
843
935
|
className
|
|
@@ -846,13 +938,14 @@ declare function ProductCardImage({
|
|
|
846
938
|
declare function ProductCardTitle({
|
|
847
939
|
className
|
|
848
940
|
}: ProductCardPartProps): ReactElement;
|
|
849
|
-
/** Up to
|
|
941
|
+
/** Up to two lines of the product or sample description. Renders nothing without one. */
|
|
850
942
|
declare function ProductCardDescription({
|
|
851
943
|
className
|
|
852
944
|
}: ProductCardPartProps): ReactElement | null;
|
|
853
945
|
/**
|
|
854
946
|
* "Sale" when some SKU's compare-at price is above that SKU's price. Without SKU prices, as in the catalog list, only
|
|
855
|
-
* when the lowest compare-at price is above the highest price.
|
|
947
|
+
* when the lowest compare-at price is above the highest price. For a sample, when its `compareAtPrice` is above its
|
|
948
|
+
* price. Renders nothing otherwise.
|
|
856
949
|
*/
|
|
857
950
|
declare function ProductCardBadge({
|
|
858
951
|
className
|
|
@@ -976,7 +1069,7 @@ declare function ProductDetailsRoot({
|
|
|
976
1069
|
/** The packaged product page for `${productPath}/:productId`. Compose the parts for a custom layout. */
|
|
977
1070
|
declare function ProductDetails(): ReactElement;
|
|
978
1071
|
interface ProductDetailsBackLinkProps extends ProductDetailsPartProps {
|
|
979
|
-
/** Replaces the chevron and
|
|
1072
|
+
/** Replaces the chevron and the `backToShop` message. */
|
|
980
1073
|
children?: ReactNode;
|
|
981
1074
|
}
|
|
982
1075
|
/** A link to the catalog. */
|
|
@@ -1068,7 +1161,7 @@ declare function ProductDetailsAddToCart({
|
|
|
1068
1161
|
interface RelatedProductsProps {
|
|
1069
1162
|
/** The product to leave out. Defaults to the route's `:productId` parameter. */
|
|
1070
1163
|
productId?: string;
|
|
1071
|
-
/** The H2. Defaults to "You may also like". */
|
|
1164
|
+
/** The H2. Defaults to "You may also like", or the provider's `relatedTitle` message. `null` leaves it out. */
|
|
1072
1165
|
title?: ReactNode;
|
|
1073
1166
|
/** The most products to show, a whole number from 1 to 24. Defaults to 4. */
|
|
1074
1167
|
limit?: number;
|
|
@@ -1094,4 +1187,4 @@ declare function RelatedProducts({
|
|
|
1094
1187
|
//#region src/storefront-surface.d.ts
|
|
1095
1188
|
declare function CommerceStatus(): ReactElement | null;
|
|
1096
1189
|
//#endregion
|
|
1097
|
-
export { AddToCartButton, type AddToCartButtonProps, AddToCartItemInput, type AddToCartLabelState, type AddedCartItem, ApiError, type CartActionPartProps, CartAddress, CartButton, type CartButtonProps, CartCheckout, CartCheckoutNote, CartClose, CartContinueShopping, CartDescription, CartDiscount, CartDrawer, CartDrawerRoot, type CartDrawerRootProps, CartEmpty, type CartEmptyProps, CartItemImage, CartItemName, CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, type CartItemRootProps, type CartItemState, CartItems, type CartItemsProps, CartLineItem, CartLineItemDetails, CartNote, CartNotices, CartOrder, type CartPartProps, CartRoot, type CartRootProps, CartSelectedAddon, CartSelectedAddonValue, CartSelectedOption, CartShippingInfo, type CartState, CartSubtotal, CartSummary, type CartSummaryProps, CartSummaryTotals, CartTax, type CartTextPartProps, CartTitle, Catalog, CatalogEmpty, type CatalogEmptyProps, CatalogHeader, type CatalogHeaderProps, CatalogPagination, type CatalogPartProps, CatalogProducts, type CatalogProductsProps, type CatalogProps, CatalogRoot, type CatalogRootProps, CatalogSummary, type CommerceContextValue, type CommerceEvent, type CommerceOperation, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, type GetSwatch, InventoryCount, LabelFilter, LineItemTotals, MediaObject, Money, OrderTotals, PageInfo, type PartLabel, PriceRange, ProductCard, ProductCardAction, type ProductCardActionLabelState, type ProductCardActionProps, ProductCardBadge, ProductCardDescription, ProductCardImage, type ProductCardPartProps, ProductCardPrice, type ProductCardProps, ProductCardRoot, type ProductCardRootProps, type ProductCardState, ProductCardSwatches, ProductCardTitle, ProductDetails, ProductDetailsAddToCart, type ProductDetailsAddToCartProps, ProductDetailsAvailability, ProductDetailsBackLink, type ProductDetailsBackLinkProps, ProductDetailsBadge, ProductDetailsDescription, type ProductDetailsErrorState, ProductDetailsGallery, ProductDetailsOption, type ProductDetailsOptionProps, type ProductDetailsOptionState, type ProductDetailsOptionValueState, ProductDetailsOptions, type ProductDetailsPartProps, ProductDetailsPrice, ProductDetailsPurchase, ProductDetailsPurchaseStatus, ProductDetailsQuantity, ProductDetailsRoot, type ProductDetailsRootProps, type ProductDetailsState, type ProductDetailsStatus, ProductDetailsTitle, ProductDetailsVariablesInput, ProductGridVariablesInput, ProductImage, type ProductImageProps, RelatedProducts, type RelatedProductsProps, SKU, SKUAttributeValue, SKUGroup, SKUGroupAttribute, SKUGroupAttributeValue, SKUGroupSKU, SKUPrice, SkuGroupResult, SkuGroupVariables, SkuGroupsResult, SkuGroupsVariables, SkuResult, SkuVariables, type StorefrontConfig, StorefrontProductAttribute, StorefrontProductAttributeValue, type StorefrontTheme, StringInFilter, type SwatchValue, addToCart, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getProductName, getSingleMatchedSku, getSingleMatchedSkuId, getSkuAttributeValueNames, getStartingCompareAt, inSentence, isOnSale, isProductOnSale, money, useCart, useCartItem, useCommerce, useMoney, useProductCard, useProductDetails, useProductDetailsOption };
|
|
1190
|
+
export { AddToCartButton, type AddToCartButtonProps, AddToCartItemInput, type AddToCartLabelState, type AddedCartItem, ApiError, type CartActionPartProps, CartAddress, CartButton, type CartButtonProps, CartCheckout, CartCheckoutNote, CartClose, CartContinueShopping, CartDescription, CartDiscount, CartDrawer, CartDrawerRoot, type CartDrawerRootProps, CartEmpty, type CartEmptyProps, CartItemImage, CartItemName, CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, type CartItemRootProps, type CartItemState, CartItems, type CartItemsProps, CartLineItem, CartLineItemDetails, CartNote, CartNotices, CartOrder, type CartPartProps, CartRoot, type CartRootProps, CartSelectedAddon, CartSelectedAddonValue, CartSelectedOption, CartShippingInfo, type CartState, CartSubtotal, CartSummary, type CartSummaryProps, CartSummaryTotals, CartTax, type CartTextPartProps, CartTitle, Catalog, CatalogEmpty, type CatalogEmptyProps, CatalogHeader, type CatalogHeaderProps, CatalogPagination, type CatalogPartProps, CatalogProducts, type CatalogProductsProps, type CatalogProps, CatalogRoot, type CatalogRootProps, type CatalogState, CatalogSummary, type CommerceContextValue, type CommerceErrorCode, type CommerceEvent, type CommerceOperation, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, type GetSwatch, InventoryCount, LabelFilter, LineItemTotals, MediaObject, type MessageValues, Money, OrderTotals, PageInfo, type PartLabel, PriceRange, ProductCard, ProductCardAction, type ProductCardActionLabelState, type ProductCardActionProps, ProductCardBadge, ProductCardDescription, ProductCardImage, type ProductCardPartProps, ProductCardPrice, type ProductCardProps, ProductCardRoot, type ProductCardRootProps, type ProductCardState, ProductCardSwatches, ProductCardTitle, ProductDetails, ProductDetailsAddToCart, type ProductDetailsAddToCartProps, ProductDetailsAvailability, ProductDetailsBackLink, type ProductDetailsBackLinkProps, ProductDetailsBadge, ProductDetailsDescription, type ProductDetailsErrorState, ProductDetailsGallery, ProductDetailsOption, type ProductDetailsOptionProps, type ProductDetailsOptionState, type ProductDetailsOptionValueState, ProductDetailsOptions, type ProductDetailsPartProps, ProductDetailsPrice, ProductDetailsPurchase, ProductDetailsPurchaseStatus, ProductDetailsQuantity, ProductDetailsRoot, type ProductDetailsRootProps, type ProductDetailsState, type ProductDetailsStatus, ProductDetailsTitle, ProductDetailsVariablesInput, ProductGridVariablesInput, ProductImage, type ProductImageProps, RelatedProducts, type RelatedProductsProps, SKU, SKUAttributeValue, SKUGroup, SKUGroupAttribute, SKUGroupAttributeValue, SKUGroupSKU, SKUPrice, type SampleProduct, SkuGroupResult, SkuGroupVariables, SkuGroupsResult, SkuGroupsVariables, SkuResult, SkuVariables, type StorefrontConfig, type StorefrontMessage, type StorefrontMessageKey, type StorefrontMessages, StorefrontProductAttribute, StorefrontProductAttributeValue, type StorefrontTheme, StringInFilter, type SwatchValue, addToCart, enUS, formatMessage, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getProductName, getSingleMatchedSku, getSingleMatchedSkuId, getSkuAttributeValueNames, getStartingCompareAt, inSentence, isOnSale, isProductOnSale, money, moneyRange, useCart, useCartItem, useCatalog, useCommerce, useMessage, useMoney, useMoneyRange, useProductCard, useProductDetails, useProductDetailsOption };
|