@springmicro/cart

A package for eCommerce sites that provides shopping cart functionality.

Exports

Components

CartProvider

Provides and handles all the data for the cart. Requires a ReactNode child. apiUrl will be modified to end with /api/ecommerce/cart. If the user object changes, the provider automatically logs in and out of the cart.

Required props:

user={({ id: number | string } & any) | undefined}
apiUrl={string}

CartContext

Allows all scopes under the CartProvider to read from the cart data and the functions to modify the cart.

Provisions:

• cart: Cart
• • Provides cart and authentication data.
• addToCart: (product: CartProduct) => void
• • Adds a product to the cart.
• removeFromCart: (i: number) => void
• • Removes an item from the cart at the given index.
• clearCart: () => void
• • Clears the cart.

CartButton

A frontend-facing component to display the cart contents in a Modal. This component is designed to go in a top navbar, ideally on the right-hand side. This component is required to be in a CartProvider scope.

Types

Cart

The type of the cart in CartContext.cart.

{
  cart: CartProducts[],
  authentication: {loggedIn: boolean, user_id: string | number}
}

CartProduct

The type of the products listed in Cart.cart.

{
  id: number | string,
  name: string,
  quantity: number | undefined
}

ProductList

Shows the products of an ecommerce category as a responsive grid of product cards. Only API_URL and category_id are required; everything else is optional with defaults.

<ProductList API_URL={suiteUrl} category_id={3} />

Options (all optional):

• Layout: columns (number, or { xs, sm, md, lg, xl }), maxColumns, cardMaxWidth, gap, justify, hideBorder, hideCategoryName.
• Card: layout ("vertical" or "horizontal"), imagePosition (top, bottom, left, right), imageAspectRatio, imageFit.
• Parts: show={{ image, name, description, price, variant, quantity, button }}. Quantity is off by default; the others are on.
• Button: buttonLabel, buttonVariant ("solid", "outline", "text"), busy.
• Pricing: currency, locale (default "en-US"). A compare-at price is shown when a price's metadata.compare_at_amount (in cents) is above its unit amount.
• Links: productHref(product) returns the link, or null for no link. Default /product/{id}.
• Styling: classNames (per part, see ClassNamePart), cssVars (--smc-* tokens, listed at the top of src/product-list/product-list.css).
• Render overrides: renderCard, renderImage, renderPrice, renderButton. Each gets defaultNode to wrap or replace.
• Slots: renderLoading (default: a skeleton), renderEmpty and renderError (default: nothing).

ProductCard takes the card options too, plus component to replace the card entirely. All option types are exported from the package root (ProductListProps, ProductCardOptions, ClassNames, ...).

SimilarProducts

Shows products similar to one product, usually under it on a product page. Needs the shop's GET /api/ecommerce/products/{id}/similar (API DB suite, ecommerce module).

<SimilarProducts API_URL={suiteUrl} product_id={12} />

What is similar is decided by the shop, from each product's metadata (editable in the admin panel under "Part numbers & similar products"): products picked by hand (related_product_ids) first, then the same part number or a cross reference (part_number, cross_references), then shared tags, then the same category. Suggestions that are marked "type": "indirect" get a note ("Suggested match. Please confirm before ordering.").

Options (all optional): limit (default 4), heading (default "Similar products", "" hides it), unverifiedNote ("" hides it), hideWhenEmpty (default true), plus every layout, card, styling and slot option of ProductList (columns, layout, show, classNames, cssVars, renderEmpty, ...). It renders nothing while the product has no similar products.

PartNumberSearch

A search box for part numbers ("I have part X, which of your products replaces it?"). It calls GET /api/ecommerce/products/cross-reference?q= and shows the matching products as cards.

<PartNumberSearch API_URL={suiteUrl} initialQuery={new URLSearchParams(location.search).get("q") ?? ""} />

Options (all optional): initialQuery, placeholder, buttonText, emptyText, unverifiedNote, onSearch(query) (e.g. to keep the number in the page address), and the same layout, card and styling options as above. Input is cleaned like the API does (letters and numbers only, uppercase); normalizePartNumber is exported too.