@godaddy/gd-commerce-storefront 0.9.0 → 0.10.0

package/README.md

@@ -57,6 +57,7 @@ Use the providers your application already has; do not create another router or
 | `onItemAdded` | unset | Called with `{ name, quantity, isSample }` after each add, live or sample; use it to confirm adds on a site with a cart page instead of a drawer |
 | `onEvent` | unset | Called with a [`CommerceEvent`](#events) for every cart change and failure, such as for analytics |
 | `locale` | `en-US` | BCP 47 locale for formatting prices, such as `de-DE`; an invalid tag falls back to `en-US` with a development warning. It never selects UI text |
+| `messages` | English | The package's text, such as `frFR`. Keys left out stay English. See [translations](#translations) |
 | `theme` | inherited text and transparent wrappers; neutral control palette | CSS custom properties applied to storefront surfaces and the portalled drawer |
 | `getSwatch` | unset | Swatches for attribute values, such as colors. Returns a CSS `background` for a value, or nothing. See [swatches](#swatches) |
 
@@ -92,7 +93,7 @@ The stylesheet includes all required utilities and scopes them to the package's
 
 By default, `.commerce-storefront` wrappers do not paint a background and inherit the host's text color. Set page and section backgrounds on the host application's layout elements. Muted text, hairlines, image placeholders and the quieter outlined buttons (cart button, product card actions, pagination) derive from the inherited text color, so they read on a light or dark page without configuration. `--commerce-surface` colors form inputs and the opaque cart drawer, paired with `--commerce-text`; it does not color component wrappers. Error and warning messages bring their own light background. The Sale badge fills with `--commerce-sale` behind `--commerce-on-sale` text, so it reads over an image and on any page; sale prices keep the surrounding text color, with the compare-at price struck through beside them. Images have square corners; `--commerce-radius` rounds buttons, inputs and option buttons. Primary buttons use `--commerce-accent` and are ringed in it on focus, so choose an accent that contrasts with the page. Set `--commerce-surface` and `--commerce-text` together to adapt controls and the drawer to a dark theme. Avoid setting wrapper backgrounds through CSS or the `theme` prop's `background`, `backgroundColor`, or `backgroundImage` properties, which can still override the transparent default. Descendants inherit the surface text and body font instead of global heading styles. Keep text, controls and focus indicators accessible when changing colors. Internal utility class names and markup are not a customization API; use the [product](#custom-product-layouts), [catalog](#custom-catalog-layouts) and [cart](#custom-cart-layouts) parts to change a layout, and the [styling hooks](#styling-hooks) to style inside a part.
 
-Prices follow the provider's `locale`, which defaults to `en-US`. UI text is English. The catalog title and description are configurable through `CatalogHeader`, and many parts take [replacement text](#replacing-text). Full localization is outside this initial API. When it arrives, translated text will be a separate prop that a site opts into; `locale` will keep formatting only, so a site that sets it for prices never gets new wording in a minor release. Replacement text will still take priority over translations.
+Prices follow the provider's `locale`, which defaults to `en-US`. UI text is English unless the site sets [`messages`](#translations).
 
 ## Compatibility
 
@@ -117,7 +118,8 @@ The repository example uses React Router 7. Follow each router version's own Rea
 | `AddToCartButton` | Adds a verified `sku`, `name`, and optional integer `quantity`; while disabled, its accessible description says why. Its children replace the label |
 | `CommerceStatus` | Connection progress/error/retry for custom layouts |
 | `useCommerce` | Cart, connection, pending/error state and serialized cart actions |
-| `useMoney` | Formats minor units in the provider's `locale`, like the package's own prices, for custom parts |
+| `useMoney` | Formats minor units in the provider's `locale`, like the package's own prices, for custom parts. `useMoneyRange` formats a range |
+| `useMessage` | The provider's [text](#translations) by key, for custom parts |
 | `ProductImage` | A product image with the package's placeholder for a missing or broken image, for custom parts |
 | `CommerceProvider` | Lower-level composition when the recommended wrapper does not fit, such as a custom drawer; mount it once |
 
@@ -433,7 +435,30 @@ Parts whose wording a site often changes take replacement content as children. T
 | `ProductCardAction` | `{ action, busy, soldOut }` |
 | `ProductDetailsBackLink` | Content only |
 
-A replaced label stays the start of the control's accessible name, so voice control users can say what they see. Where the package adds the product name for screen readers, it follows as visually hidden text: `<CartItemRemove>Delete</CartItemRemove>` is named "Delete Mug". Controls without replacement text, such as "Increase quantity of Mug", keep English names.
+A replaced label stays the start of the control's accessible name, so voice control users can say what they see. Where the package adds the product name for screen readers, it follows as visually hidden text: `<CartItemRemove>Delete</CartItemRemove>` is named "Delete Mug". Controls without replacement text, such as "Increase quantity of Mug", take their names from [`messages`](#translations).
+
+## Translations
+
+The package's text comes from the provider's `messages`. Set it with `locale` for a translated store; the two are separate, so a site that sets `locale` for prices never gets new wording.
+
+```tsx
+import { CommerceStorefront } from '@godaddy/gd-commerce-storefront';
+import { frFR } from '@godaddy/gd-commerce-storefront/messages/fr-FR';
+
+<CommerceStorefront locale='fr-FR' messages={frFR}>
+```
+
+French is its own import, so English-only sites do not load it. Pass only the keys to change, and the rest stay as they were, English by default: `messages={{ ...frFR, checkout: 'Commander' }}`. The `StorefrontMessages` type lists every key, and `enUS` has the English text. New keys may be added in minor releases and stay English until translated, so type a translation of your own as `Partial<StorefrontMessages>`.
+
+Messages are plain data, so they can come from JSON, a translation service, or a server component. `{name}` placeholders are filled in, and numbers in them are formatted for the messages' `locale`. A message with a count can have plural forms, chosen by the language's rules; French counts 0 as singular:
+
+```ts
+{ productCount: { one: '{count} produit affiché', other: '{count} produits affichés' } }
+```
+
+The server's failure messages are English. With English text the storefront shows them as they are; with any other language it shows the text in `errorCodes` for the response's `code`, such as `scope_mismatch`, or the generic `requestFailed`. Product names, descriptions and attribute names come from the catalog as the merchant entered them, and are not translated. Sample prices stay in USD.
+
+[Replacement text](#replacing-text) and props such as `CatalogHeader`'s `title` take priority over `messages`. For custom parts, `useMessage()` returns the provider's text by key, `useMoney()` formats prices, and `useMoneyRange()` formats a range the way the `locale` writes it, such as `$20.00 – $25.00` or `20,00–25,00 €`.
 
 ## Styling hooks
 
@@ -458,7 +483,7 @@ Every part's outer element has a `data-commerce-part` attribute with the part's
 | `item-removed` | `itemId`, `isSample` |
 | `discount-applied` | `code` |
 | `checkout-started` | `cartId`; sent just before the browser leaves for checkout, so use `navigator.sendBeacon` or a keepalive request |
-| `error` | `operation` (`add`, `change-quantity`, `remove`, `discount`, `refresh` or `checkout`) and the `message` the cart shows |
+| `error` | `operation` (`add`, `change-quantity`, `remove`, `discount`, `refresh` or `checkout`), the `message` the cart shows in the provider's language at the time of the failure, and the server's `code`, such as `scope_mismatch`, when it sent one. The cart's own notice follows a later change of `messages`; the event's text does not, so log `code` to group failures |
 
 New event types may be added in minor releases, so ignore types you do not handle. A callback that throws or returns a rejected promise, including `onItemAdded`, is logged to the console and does not fail the cart operation. Async callbacks are not awaited, so a slow analytics call never delays the cart.
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+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";
 import { CSSProperties, ReactElement, ReactNode } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 
@@ -11,10 +12,25 @@ interface StorefrontConfig {
 }
 declare class ApiError extends Error {
   readonly status: number;
-  constructor(message: string, status: number, options?: ErrorOptions);
+  /** The failure response's `code`, such as `not_found`, when the server sent one. */
+  readonly code: string | undefined;
+  /** Package text to show in place of `message`, for failures the package describes itself. */
+  readonly text: {
+    key: StorefrontMessageKey;
+    values?: MessageValues;
+  } | undefined;
+  constructor(message: string, status: number, options?: ErrorOptions & {
+    code?: string;
+    text?: {
+      key: StorefrontMessageKey;
+      values?: MessageValues;
+    };
+  });
 }
 /** Formats minor units, such as cents, as currency. Inside the provider, prefer `useMoney`, which follows its `locale`. */
 declare function money(value: number, currency: string, locale?: string): string;
+/** Formats a range of minor units the way `locale` writes ranges, such as `$20.00 – $25.00` or `20,00–25,00 €`. */
+declare function moneyRange(min: number, max: number, currency: string, locale?: string): string;
 //#endregion
 //#region src/cart-model.d.ts
 interface Money {
@@ -150,7 +166,8 @@ interface CartSummaryTotals {
 declare function addToCart(cartId: string | null, item: AddToCartItemInput, fetchFn?: typeof globalThis.fetch): Promise<{
   cart: CartOrder | null;
 }>;
-declare function getCartSummaryTotals(order: CartOrder | null | undefined): CartSummaryTotals;
+/** The cart's totals in minor units. `currencyCode` is the cart's, or `fallbackCurrency`, such as the store's. */
+declare function getCartSummaryTotals(order: CartOrder | null | undefined, fallbackCurrency?: string): CartSummaryTotals;
 //#endregion
 //#region src/catalog-model.d.ts
 interface PageInfo {
@@ -580,8 +597,10 @@ declare function CatalogRoot({
   urlState
 }: CatalogRootProps): ReactElement;
 interface CatalogHeaderProps extends CatalogPartProps {
-  title?: string;
-  description?: string;
+  /** Defaults to the provider's `catalogTitle` message. `null` leaves the heading out. */
+  title?: string | null;
+  /** Defaults to the provider's `catalogDescription` message. `null` leaves it out. */
+  description?: string | null;
 }
 /** The catalog title as the page's H1, with a description. */
 declare function CatalogHeader({
@@ -655,6 +674,8 @@ interface CommerceContextValue {
   config: StorefrontConfig;
   /** The BCP 47 locale that prices are formatted in, such as `en-US`. */
   locale: string;
+  /** The package's text: English, with the provider's `messages` over it. */
+  messages: StorefrontMessages;
   cart: CartOrder | null;
   /** Whether the cart drawer is open. Always `false` when no `CartDrawer` or `CartDrawerRoot` is mounted. */
   open: boolean;
@@ -680,6 +701,13 @@ declare function useCommerce(): CommerceContextValue;
  * store's currency unless `currency` is given.
  */
 declare function useMoney(): (value: number, currency?: string) => string;
+/** `useMoney` for a range, such as `$20.00 – $25.00`, written the way the provider's `locale` writes ranges. */
+declare function useMoneyRange(): (min: number, max: number, currency?: string) => string;
+/**
+ * The provider's text for `key`, with `{placeholders}` filled from `values`, the way the package's own parts read
+ * it. For custom parts that should match the package's language. English outside a provider.
+ */
+declare function useMessage(): (key: StorefrontMessageKey, values?: MessageValues) => string;
 type StorefrontTheme = CSSProperties & {
   '--commerce-accent'?: string;
   '--commerce-accent-hover'?: string;
@@ -718,9 +746,15 @@ interface CommerceProviderProps {
   checkoutSuccessPath?: string;
   /**
    * The BCP 47 locale for formatting prices, such as `de-DE`. Defaults to `en-US`; an invalid tag falls back to it.
-   * It never selects UI text: localized text will be a separate, opt-in prop, so setting `locale` cannot change wording.
+   * It never selects UI text; set `messages` for that.
    */
   locale?: string;
+  /**
+   * The package's text, such as `frFR` from `@godaddy/gd-commerce-storefront/messages/fr-FR`. Keys left out use
+   * English. Independent of `locale`, so set both for a translated store. Part `children` and props such as
+   * `CatalogHeader`'s `title` still replace the text where given.
+   */
+  messages?: Partial<StorefrontMessages>;
   /**
    * Called after an item is added, live or sample. With a drawer mounted, the drawer also opens. Without one, such as
    * on a site with a cart page, use it to confirm the add.
@@ -759,10 +793,14 @@ type CommerceEvent = {
   readonly type: 'checkout-started';
   readonly cartId: string;
 }
-/** `message` is the one the cart shows. */ | {
+/**
+ * `message` is the one the cart shows, in the provider's language. `code` is the server's failure code, such as
+ * `scope_mismatch`, when it sent one.
+ */ | {
   readonly type: 'error';
   readonly operation: CommerceOperation;
   readonly message: string;
+  readonly code?: string;
 };
 /** The item passed to `onItemAdded`. */
 interface AddedCartItem {
@@ -779,6 +817,7 @@ declare function CommerceProvider({
   theme,
   getSwatch,
   locale,
+  messages,
   onItemAdded,
   onEvent
 }: CommerceProviderProps): ReactElement;
@@ -976,7 +1015,7 @@ declare function ProductDetailsRoot({
 /** The packaged product page for `${productPath}/:productId`. Compose the parts for a custom layout. */
 declare function ProductDetails(): ReactElement;
 interface ProductDetailsBackLinkProps extends ProductDetailsPartProps {
-  /** Replaces the chevron and "Back to shop". */
+  /** Replaces the chevron and the `backToShop` message. */
   children?: ReactNode;
 }
 /** A link to the catalog. */
@@ -1068,7 +1107,7 @@ declare function ProductDetailsAddToCart({
 interface RelatedProductsProps {
   /** The product to leave out. Defaults to the route's `:productId` parameter. */
   productId?: string;
-  /** The H2. Defaults to "You may also like". */
+  /** The H2. Defaults to "You may also like", or the provider's `relatedTitle` message. `null` leaves it out. */
   title?: ReactNode;
   /** The most products to show, a whole number from 1 to 24. Defaults to 4. */
   limit?: number;
@@ -1094,4 +1133,4 @@ declare function RelatedProducts({
 //#region src/storefront-surface.d.ts
 declare function CommerceStatus(): ReactElement | null;
 //#endregion
-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 };
+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 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, 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, useCommerce, useMessage, useMoney, useMoneyRange, useProductCard, useProductDetails, useProductDetailsOption };