@laconius/cart 0.1.0

package/src/components.tsx

@@ -0,0 +1,237 @@
+import { getErrorMessage, getPrimaryImage, useTranslation } from '@laconius/core';
+import {
+  Button,
+  Divider,
+  Media,
+  Price,
+  QuantityStepper,
+  Text,
+  useStyles,
+  useUiComponent,
+  type Theme,
+} from '@laconius/ui';
+import {
+  AccessibilityInfo,
+  StyleSheet,
+  View,
+  type ImageStyle,
+  type StyleProp,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native';
+
+import type { Cart, OrderEntry } from './models';
+import { useAddToCart, useRemoveCartEntry, useUpdateCartEntry } from './queries';
+
+export type AddToCartButtonProps = {
+  productCode: string;
+  quantity?: number;
+  disabled?: boolean;
+  /** Root style. */
+  style?: StyleProp<ViewStyle>;
+  /** Named inner parts — public, versioned API. */
+  styles?: {
+    container?: StyleProp<ViewStyle>;
+    error?: StyleProp<TextStyle>;
+  };
+};
+
+/**
+ * The one component with no UI hook: its logic *is* the mutation
+ * ([chapter 07](../../../docs/spec/07-ui-kit.md)). An OCC business error — out of stock, most
+ * likely — reaches the user as a translated sentence, per hook, with no message bus.
+ */
+export function AddToCartButton({
+  productCode,
+  quantity = 1,
+  disabled = false,
+  style,
+  styles: parts,
+}: AddToCartButtonProps) {
+  const t = useTranslation();
+  const sheet = useStyles(createStyles);
+  const Action = useUiComponent('Button', Button);
+  const addToCart = useAddToCart();
+
+  return (
+    <View style={[sheet.addToCart, parts?.container, style]}>
+      <Action
+        title={t('cart.addToCart')}
+        accessibilityLabel={t('cart.addToCart')}
+        loading={addToCart.isPending}
+        disabled={disabled || addToCart.isPending || !productCode}
+        onPress={() =>
+          addToCart.mutate(
+            { productCode, quantity },
+            {
+              onSuccess: () =>
+                AccessibilityInfo.announceForAccessibility(t('cart.itemAdded')),
+              onError: (error) =>
+                AccessibilityInfo.announceForAccessibility(getErrorMessage(error, t)),
+            },
+          )
+        }
+      />
+      {addToCart.error ? (
+        <Text variant="caption" style={[sheet.error, parts?.error]}>
+          {getErrorMessage(addToCart.error, t)}
+        </Text>
+      ) : null}
+    </View>
+  );
+}
+
+export type CartEntryRowProps = {
+  entry: OrderEntry;
+  /** Root style. */
+  style?: StyleProp<ViewStyle>;
+  styles?: {
+    container?: StyleProp<ViewStyle>;
+    media?: StyleProp<ImageStyle>;
+    info?: StyleProp<ViewStyle>;
+    title?: StyleProp<TextStyle>;
+    price?: StyleProp<TextStyle>;
+    error?: StyleProp<TextStyle>;
+  };
+};
+
+/** Quantity and remove, one mutation hook each so each keeps its own `isPending` and `error`. */
+export function CartEntryRow({ entry, style, styles: parts }: CartEntryRowProps) {
+  const t = useTranslation();
+  const sheet = useStyles(createStyles);
+  const Remove = useUiComponent('Button', Button);
+  const update = useUpdateCartEntry();
+  const remove = useRemoveCartEntry();
+
+  const entryNumber = entry.entryNumber;
+  const busy = update.isPending || remove.isPending;
+  const error = update.error ?? remove.error;
+
+  return (
+    <View style={[sheet.row, parts?.container, style]}>
+      <Media
+        media={getPrimaryImage(entry.product?.images)}
+        mediaRole="cartIcon"
+        decorative
+        style={[sheet.rowMedia, parts?.media]}
+      />
+      <View style={[sheet.rowInfo, parts?.info]}>
+        <Text variant="label" numberOfLines={2} style={parts?.title}>
+          {entry.product?.name}
+        </Text>
+        <Price price={entry.totalPrice} variant="label" style={parts?.price} />
+        <View style={sheet.rowActions}>
+          <QuantityStepper
+            value={entry.quantity ?? 1}
+            max={entry.product?.stock?.stockLevel}
+            disabled={entryNumber === undefined || busy}
+            onChange={(value) => {
+              if (entryNumber === undefined) return;
+              update.mutate(
+                { entryNumber, quantity: value },
+                {
+                  onSuccess: () =>
+                    AccessibilityInfo.announceForAccessibility(t('cart.quantityUpdated')),
+                },
+              );
+            }}
+          />
+          <Remove
+            variant="ghost"
+            title={t('cart.remove')}
+            accessibilityLabel={t('cart.removeItem', { name: entry.product?.name ?? '' })}
+            disabled={entryNumber === undefined || busy}
+            onPress={() => {
+              if (entryNumber === undefined) return;
+              remove.mutate(
+                { entryNumber },
+                {
+                  onSuccess: () =>
+                    AccessibilityInfo.announceForAccessibility(t('cart.itemRemoved')),
+                },
+              );
+            }}
+          />
+        </View>
+        {error ? (
+          <Text variant="caption" style={[sheet.error, parts?.error]}>
+            {getErrorMessage(error, t)}
+          </Text>
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
+export type CartTotalsProps = {
+  cart?: Cart;
+  /** Root style. */
+  style?: StyleProp<ViewStyle>;
+  styles?: {
+    container?: StyleProp<ViewStyle>;
+    row?: StyleProp<ViewStyle>;
+    label?: StyleProp<TextStyle>;
+    value?: StyleProp<TextStyle>;
+  };
+};
+
+/** Pure component: the cart arrives as a prop, exactly like `Price` ([chapter 07](../../../docs/spec/07-ui-kit.md)). */
+export function CartTotals({ cart, style, styles: parts }: CartTotalsProps) {
+  const t = useTranslation();
+  const sheet = useStyles(createStyles);
+  if (!cart) return null;
+
+  const rows: { key: string; label: string; price: Cart['subTotal'] }[] = [];
+  if (cart.subTotal) rows.push({ key: 'subtotal', label: t('cart.subtotal'), price: cart.subTotal });
+  if (cart.totalDiscounts?.value) {
+    rows.push({ key: 'discounts', label: t('cart.discounts'), price: cart.totalDiscounts });
+  }
+  if (cart.deliveryCost) {
+    rows.push({ key: 'delivery', label: t('cart.delivery'), price: cart.deliveryCost });
+  }
+  if (cart.totalTax?.value) rows.push({ key: 'tax', label: t('cart.tax'), price: cart.totalTax });
+
+  return (
+    <View style={[sheet.totals, parts?.container, style]}>
+      {rows.map((row) => (
+        <View key={row.key} style={[sheet.totalsRow, parts?.row]}>
+          <Text variant="caption" muted style={parts?.label}>
+            {row.label}
+          </Text>
+          <Price price={row.price} variant="caption" style={parts?.value} />
+        </View>
+      ))}
+      <Divider />
+      <View style={[sheet.totalsRow, parts?.row]}>
+        <Text variant="label" style={parts?.label}>
+          {t('cart.total')}
+        </Text>
+        <Price
+          price={cart.totalPriceWithTax ?? cart.totalPrice}
+          variant="subheading"
+          style={parts?.value}
+        />
+      </View>
+    </View>
+  );
+}
+
+const createStyles = (theme: Theme) =>
+  StyleSheet.create({
+    addToCart: { gap: theme.spacing.xs },
+    error: { color: theme.colors.danger },
+    row: { flexDirection: 'row', gap: theme.spacing.md },
+    rowMedia: { width: 64, height: 64, borderRadius: theme.radii.sm },
+    rowInfo: { flex: 1, gap: theme.spacing.xs },
+    rowActions: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+    },
+    totals: { gap: theme.spacing.xs },
+    totalsRow: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+    },
+  });

package/src/config.ts

@@ -0,0 +1,81 @@
+import type { LaconiusConfigChunk } from '@laconius/core';
+import type { CmsComponentMapping } from '@laconius/cms';
+
+import { defaultCartConverters, type CartAdapter } from './adapter';
+import { CmsMiniCart } from './defaults';
+import { defaultCartTranslations } from './translations';
+
+declare module '@laconius/ui' {
+  /** The cart components, replaceable through the typed UI registry. */
+  interface LaconiusUiComponents {
+    AddToCartButton: unknown;
+    CartEntryRow: unknown;
+    CartTotals: unknown;
+  }
+}
+
+declare module '@laconius/core' {
+  interface LaconiusEndpoints {
+    carts: string | Record<string, string>;
+    cart: string | Record<string, string>;
+    createCart: string | Record<string, string>;
+    deleteCart: string | Record<string, string>;
+    addEntries: string | Record<string, string>;
+    updateEntries: string | Record<string, string>;
+    removeEntries: string | Record<string, string>;
+    cartApplyVoucher: string | Record<string, string>;
+    cartRemoveVoucher: string | Record<string, string>;
+    cartVoucher: string | Record<string, string>;
+    validate: string | Record<string, string>;
+  }
+
+  interface LaconiusConverters {
+    cart: unknown;
+    cartModification: unknown;
+  }
+
+  interface LaconiusAdapters {
+    cart: CartAdapter;
+  }
+}
+
+/**
+ * Ported from `feature-libs/cart/base/occ/config/default-occ-cart-config-factory.ts`, minus the
+ * saved-cart fields (`saveTime`, `name`, `description` stay off the wire — v1 ships one active
+ * cart). `stock(FULL)` on entry products is what lets the stepper cap at the stock level.
+ */
+const CART_FIELDS =
+  'DEFAULT,potentialProductPromotions,appliedProductPromotions,potentialOrderPromotions,appliedOrderPromotions,entries(totalPrice(formattedValue),product(images(FULL),stock(FULL)),basePrice(formattedValue,value),updateable),totalPrice(formattedValue),totalItems,totalPriceWithTax(formattedValue),totalDiscounts(value,formattedValue),subTotal(formattedValue),totalUnitCount,deliveryItemsQuantity,deliveryCost(formattedValue),totalTax(formattedValue,value),pickupItemsQuantity,net,appliedVouchers,productDiscounts(formattedValue),user';
+
+export const defaultCartEndpoints = {
+  carts: 'users/${userId}/carts?fields=carts(' + CART_FIELDS + ')',
+  cart: 'users/${userId}/carts/${cartId}?fields=' + CART_FIELDS,
+  createCart: 'users/${userId}/carts?fields=' + CART_FIELDS,
+  deleteCart: 'users/${userId}/carts/${cartId}',
+  addEntries: 'users/${userId}/carts/${cartId}/entries',
+  updateEntries: 'users/${userId}/carts/${cartId}/entries/${entryNumber}',
+  removeEntries: 'users/${userId}/carts/${cartId}/entries/${entryNumber}',
+  cartApplyVoucher: 'users/${userId}/carts/${cartId}/applyVoucher',
+  cartRemoveVoucher: 'users/${userId}/carts/${cartId}/removeVoucher',
+  /** The legacy pair, used when `capabilities.jsonVouchers` is off. */
+  cartVoucher: {
+    default: 'users/${userId}/carts/${cartId}/vouchers',
+    delete: 'users/${userId}/carts/${cartId}/vouchers/${voucherId}',
+  },
+  validate: 'users/${userId}/carts/${cartId}/validate?fields=DEFAULT',
+};
+
+/**
+ * The content types that read cart data ship here rather than in `@laconius/cms`, which keeps
+ * the dependency arrow `cart -> cms` ([chapter 01](../../../docs/spec/01-packages.md)).
+ */
+export const defaultCartCmsComponents: Record<string, CmsComponentMapping> = {
+  MiniCartComponent: { component: CmsMiniCart },
+};
+
+export const defaultCartConfig: LaconiusConfigChunk = {
+  backend: { occ: { endpoints: defaultCartEndpoints } },
+  cms: { components: defaultCartCmsComponents },
+  converters: defaultCartConverters,
+  i18n: { translations: defaultCartTranslations },
+};

package/src/defaults.tsx

@@ -0,0 +1,53 @@
+import { useTranslation } from '@laconius/core';
+import { useCmsComponentData, useCmsNavigate, type CmsComponent } from '@laconius/cms';
+import { Price, Text, useStyles, type Theme } from '@laconius/ui';
+import { Pressable, StyleSheet } from 'react-native';
+
+import { useActiveCart } from './queries';
+
+/** Spartacus' `CmsMiniCartComponent` fields; the lightbox banner is web furniture and dropped. */
+export interface CmsMiniCartData extends CmsComponent {
+  title?: string;
+  shownProductCount?: string;
+  /** `TOTAL` or `SUBTOTAL`. */
+  totalDisplay?: string;
+}
+
+/**
+ * Item count and total. It ships here rather than in `@laconius/cms` because it reads cart data,
+ * which is what keeps the dependency arrow `cart -> cms`
+ * ([chapter 01](../../../docs/spec/01-packages.md)) — the same reason Spartacus ships
+ * `MiniCartComponent` from `feature-libs/cart/base/components/mini-cart/`.
+ */
+export function CmsMiniCart() {
+  const data = useCmsComponentData<CmsMiniCartData>();
+  const t = useTranslation();
+  const sheet = useStyles(createStyles);
+  const navigate = useCmsNavigate();
+  const { data: cart } = useActiveCart();
+
+  const count = cart?.totalUnitCount ?? cart?.totalItems ?? 0;
+  const total = data.totalDisplay === 'SUBTOTAL' ? cart?.subTotal : cart?.totalPrice;
+
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={`${data.title ?? t('cart.title')}: ${t('cart.entryCount', { count })}`}
+      onPress={() => navigate({ kind: 'url', url: '/cart', external: false })}
+      style={sheet.root}
+    >
+      <Text variant="label">{t('cart.entryCount', { count })}</Text>
+      {count > 0 && total ? <Price price={total} variant="label" /> : null}
+    </Pressable>
+  );
+}
+
+const createStyles = (theme: Theme) =>
+  StyleSheet.create({
+    root: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: theme.spacing.sm,
+      minHeight: 44,
+    },
+  });

package/src/index.ts

@@ -0,0 +1,61 @@
+export type {
+  AddToCartInput,
+  Cart,
+  CartMergeFailure,
+  CartMergeResult,
+  CartModification,
+  CartModificationList,
+  CartMutationResult,
+  CartValidationStatusCode,
+  DeliveryMode,
+  OrderEntry,
+  PromotionOrderEntryConsumed,
+  PromotionResult,
+  Voucher,
+} from './models';
+
+export {
+  getCartId,
+  normalizeCartImages,
+  type OccCart,
+  type OccOrderEntry,
+} from './normalizer';
+
+export {
+  cartAdapter,
+  defaultCartAdapter,
+  defaultCartConverters,
+  type CartAdapter,
+} from './adapter';
+
+export {
+  cartQueries,
+  useActiveCart,
+  useAddToCart,
+  useApplyVoucher,
+  useMergeAnonymousCart,
+  useRemoveCartEntry,
+  useRemoveVoucher,
+  useUpdateCartEntry,
+} from './queries';
+
+export { useActiveCartIdStore, type ActiveCartState } from './store';
+
+export {
+  AddToCartButton,
+  CartEntryRow,
+  CartTotals,
+  type AddToCartButtonProps,
+  type CartEntryRowProps,
+  type CartTotalsProps,
+} from './components';
+
+export { CmsMiniCart, type CmsMiniCartData } from './defaults';
+
+export {
+  defaultCartCmsComponents,
+  defaultCartConfig,
+  defaultCartEndpoints,
+} from './config';
+
+export { defaultCartTranslations } from './translations';

package/src/models.ts

@@ -0,0 +1,142 @@
+import type { Currency, Price, Principal, Product, Promotion } from '@laconius/core';
+
+/**
+ * Cart models, ported from Spartacus `feature-libs/cart/base/root/models/cart.model.ts`
+ * (Apache-2.0, see NOTICE), minus the B2B, saved-cart and pickup-in-store noise
+ * ([chapter 03](../../../docs/spec/03-occ-layer.md)).
+ *
+ * `CartModification` is copied **exactly**: it encodes protocol rather than data — a cart
+ * mutation answers with an adjusted quantity and a status, and an API returning `void` there
+ * would be wrong.
+ */
+
+export interface Voucher {
+  appliedValue?: Price;
+  code?: string;
+  currency?: Currency;
+  description?: string;
+  freeShipping?: boolean;
+  name?: string;
+  value?: number;
+  valueFormatted?: string;
+  valueString?: string;
+  voucherCode?: string;
+}
+
+export interface PromotionOrderEntryConsumed {
+  adjustedUnitPrice?: number;
+  code?: string;
+  orderEntryNumber?: number;
+  quantity?: number;
+}
+
+export interface PromotionResult {
+  consumedEntries?: PromotionOrderEntryConsumed[];
+  description?: string;
+  promotion?: Promotion;
+}
+
+export interface DeliveryMode {
+  code?: string;
+  deliveryCost?: Price;
+  description?: string;
+  name?: string;
+}
+
+export interface OrderEntry {
+  basePrice?: Price;
+  deliveryMode?: DeliveryMode;
+  entryNumber?: number;
+  product?: Product;
+  quantity?: number;
+  totalPrice?: Price;
+  updateable?: boolean;
+  promotions?: PromotionResult[];
+}
+
+export interface Cart {
+  appliedOrderPromotions?: PromotionResult[];
+  appliedProductPromotions?: PromotionResult[];
+  appliedVouchers?: Voucher[];
+  calculated?: boolean;
+  code?: string;
+  deliveryCost?: Price;
+  deliveryItemsQuantity?: number;
+  deliveryMode?: DeliveryMode;
+  description?: string;
+  entries?: OrderEntry[];
+  /** ISO string: OCC returns strings and never `Date`. */
+  expirationTime?: string;
+  guid?: string;
+  name?: string;
+  net?: boolean;
+  orderDiscounts?: Price;
+  pickupItemsQuantity?: number;
+  potentialOrderPromotions?: PromotionResult[];
+  potentialProductPromotions?: PromotionResult[];
+  productDiscounts?: Price;
+  site?: string;
+  store?: string;
+  subTotal?: Price;
+  totalDiscounts?: Price;
+  totalItems?: number;
+  totalPrice?: Price;
+  totalPriceWithTax?: Price;
+  totalTax?: Price;
+  totalUnitCount?: number;
+  user?: Principal;
+}
+
+export interface CartModification {
+  deliveryModeChanged?: boolean;
+  entry?: OrderEntry;
+  quantity?: number;
+  quantityAdded?: number;
+  statusCode?: string;
+  statusMessage?: string;
+}
+
+export interface CartModificationList {
+  cartModifications?: CartModification[];
+}
+
+export type CartValidationStatusCode =
+  | 'noStock'
+  | 'lowStock'
+  | 'reviewConfiguration'
+  | 'pricingError'
+  | 'unresolvableIssues'
+  | 'below_min_quantity'
+  | 'exceed_max_quantity';
+
+export type AddToCartInput = {
+  productCode: string;
+  quantity?: number;
+};
+
+/**
+ * What every cart mutation resolves to. It carries the cart id it acted on: with lazy creation,
+ * an `onSuccess` closing over `activeCartId` writes the wrong cache entry
+ * ([chapter 04](../../../docs/spec/04-state.md)).
+ */
+export type CartMutationResult = {
+  cart: Cart;
+  cartId: string;
+  modification?: CartModification;
+};
+
+export type CartMergeFailure = {
+  entry: OrderEntry;
+  /** The `LaconiusHttpError` that rejected the replay. */
+  error: unknown;
+};
+
+/**
+ * The one place Laconius returns errors as data rather than throwing them: a partial replay is
+ * not a failure, and silently dropping the rejected entries is exactly what users notice
+ * ([chapter 09](../../../docs/spec/09-i18n-and-errors.md)).
+ */
+export type CartMergeResult = {
+  replayed: OrderEntry[];
+  failed: CartMergeFailure[];
+};

package/src/normalizer.ts

@@ -0,0 +1,39 @@
+import { normalizeImages, type Image, type Product } from '@laconius/core';
+
+import type { Cart, OrderEntry } from './models';
+
+/** An entry as OCC answers it: the product's images are still a flat list. */
+export type OccOrderEntry = Omit<OrderEntry, 'product'> & {
+  product?: Omit<Product, 'images'> & { images?: Image[] };
+};
+
+export type OccCart = Omit<Cart, 'entries'> & { entries?: OccOrderEntry[] };
+
+/**
+ * Reshapes every entry product's flat image list through core's `normalizeImages` — the same
+ * mechanism the product adapter uses ([chapter 08](../../../docs/spec/08-media.md)). URLs are
+ * not absolutised here: converters are pure, so the adapter absolutises the whole payload
+ * afterwards.
+ */
+export function normalizeCartImages(source: OccCart, target?: Cart): Cart {
+  const cart = target ?? ({ ...source } as unknown as Cart);
+  if (source.entries) {
+    cart.entries = source.entries.map((entry) =>
+      entry.product?.images
+        ? ({
+            ...entry,
+            product: { ...entry.product, images: normalizeImages(entry.product.images) },
+          } as OrderEntry)
+        : (entry as OrderEntry),
+    );
+  }
+  return cart;
+}
+
+/**
+ * Ported from `feature-libs/cart/base/core/utils/utils.ts`: an anonymous cart is addressed by
+ * its `guid`, a logged-in user's cart by its `code`.
+ */
+export function getCartId(cart: Cart | undefined, userId: string): string {
+  return (userId === 'anonymous' ? cart?.guid : cart?.code) ?? '';
+}