@shopbb/helium 0.3.0-alpha.1 → 0.3.0

package/dist/components/index.js

@@ -2,13 +2,28 @@
  * @shopbb/helium/components — 商家用 React 组件
  *
  * 用法：
- *   import { Money, Image, ProductPrice, AddToCartButton } from '@shopbb/helium/components';
+ *   import {
+ *     ShopProvider, CartProvider, AnalyticsProvider,
+ *     useShop, useCart, useAnalytics,
+ *     Money, Image, ProductPrice,
+ *     AddToCartButton, CartLineQuantityAdjustButton,
+ *     VariantSelector, ProductOptionsProvider, useProductOptions,
+ *     Analytics,
+ *   } from '@shopbb/helium/components';
  *
  * 设计原则：
  *   - 无样式：组件只管行为 + 语义化 DOM，样式商家自己写
  *   - data-* 钩子：方便选择器
  *   - 对齐 Shopify Hydrogen 同名组件的 API，迁移成本低
+ *   - Provider 链：<ShopProvider> > <CartProvider> > <AnalyticsProvider> > App
+ *     组件优先从 Provider 拿；Provider 缺省时回退到 props 或 noop
  */
+// Providers + hooks
+export { ShopProvider, useShop, useShopOptional } from './ShopProvider';
+export { CartProvider, useCart, useCartOptional } from './CartProvider';
+export { ProductOptionsProvider, useProductOptions, } from './ProductOptionsProvider';
+export { AnalyticsProvider, useAnalytics, Analytics } from './AnalyticsProvider';
+// 展示型组件
 export { Money } from './Money';
 export { Image } from './Image';
 export { ProductPrice } from './ProductPrice';

package/dist/components/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAG9E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAWxE,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAOlC,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGjF,QAAQ;AACR,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAG9E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopbb/helium",
-  "version": "0.3.0-alpha.1",
+  "version": "0.3.0",
   "description": "shopbb storefront framework — components, React SSR, GraphQL client, cart handler, cache for Cloudflare Workers",
   "license": "MIT",
   "type": "module",

package/src/components/AddToCartButton.tsx

@@ -22,6 +22,8 @@
  */
 
 import * as React from 'react';
+import { useCartOptional } from './CartProvider';
+import { useAnalytics } from './AnalyticsProvider';
 
 export interface AddToCartButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'onError'> {
   /** 必传：variant 的 GID（gid://shopbb/ProductVariant/...） */
@@ -55,17 +57,26 @@ export function AddToCartButton(props: AddToCartButtonProps) {
   } = props;
 
   const [adding, setAdding] = React.useState(false);
+  const cart = useCartOptional();
+  const analytics = useAnalytics();
 
   const handleClick = async (e: React.MouseEvent<HTMLButtonElement>) => {
     e.preventDefault();
     if (adding || disabledProp) return;
-    if (!onAdd) {
-      console.warn('[AddToCartButton] onAdd not provided; this button does nothing in Phase 1');
-      return;
-    }
+
     setAdding(true);
     try {
-      await onAdd(variantId, quantity);
+      if (onAdd) {
+        // 商家显式传了 onAdd 优先用（Phase 1 兼容路径）
+        await onAdd(variantId, quantity);
+      } else if (cart) {
+        // 自动从 <CartProvider> 取
+        await cart.linesAdd([{ merchandiseId: variantId, quantity }]);
+      } else {
+        console.warn('[AddToCartButton] no onAdd and no <CartProvider> — button does nothing');
+        return;
+      }
+      analytics.emit('add_to_cart', { variantId, quantity });
       onAdded?.();
     } catch (err: any) {
       console.error('[AddToCartButton] add failed:', err);

package/src/components/AnalyticsProvider.tsx

@@ -0,0 +1,175 @@
+/**
+ * <AnalyticsProvider> + useAnalytics() + <Analytics.*> 事件组件
+ *
+ * 简单事件总线：
+ *   - 商家注册 reporters（GA / Plausible / 自家 API）
+ *   - 通过 <Analytics.PageView /> / <Analytics.ProductView /> 等组件声明式触发
+ *   - 也可以 useAnalytics().emit(name, data)
+ *
+ * 用法：
+ *   <AnalyticsProvider
+ *     onEvent={(e) => {
+ *       fetch('/api/analytics', { method: 'POST', body: JSON.stringify(e) });
+ *       window.dataLayer?.push(e);
+ *     }}
+ *   >
+ *     <App />
+ *   </AnalyticsProvider>
+ *
+ *   // 在某页：
+ *   <Analytics.PageView path="/products" title="Products" />
+ *   <Analytics.ProductView product={product} />
+ *   <Analytics.AddToCart cart={cart} addedLineId={lineId} />
+ *
+ *   // 命令式：
+ *   const { emit } = useAnalytics();
+ *   emit('search', { query: 'wireless' });
+ */
+
+import * as React from 'react';
+import { useCartOptional } from './CartProvider';
+import { useShopOptional } from './ShopProvider';
+
+export interface AnalyticsEvent {
+  /** 事件名，例如 'page_view' / 'product_view' / 'add_to_cart' */
+  name: string;
+  /** 时间戳 (ms) */
+  timestamp: number;
+  /** 当前 shop（如果在 ShopProvider 内） */
+  shop?: { storeId: string; shopName: string } | null;
+  /** 自定义 payload */
+  payload: Record<string, any>;
+}
+
+export interface AnalyticsContextValue {
+  emit: (name: string, payload?: Record<string, any>) => void;
+}
+
+const Ctx = React.createContext<AnalyticsContextValue | null>(null);
+
+export interface AnalyticsProviderProps {
+  children: React.ReactNode;
+  /** 接收所有事件的回调 */
+  onEvent?: (event: AnalyticsEvent) => void;
+  /** 是否自动监听 cart 变化触发 cart_updated 事件 */
+  trackCart?: boolean;
+}
+
+export function AnalyticsProvider(props: AnalyticsProviderProps) {
+  const { children, onEvent, trackCart = true } = props;
+  const shop = useShopOptional();
+  const cartCtx = useCartOptional();
+  const onEventRef = React.useRef(onEvent);
+  React.useEffect(() => {
+    onEventRef.current = onEvent;
+  }, [onEvent]);
+
+  const emit = React.useCallback(
+    (name: string, payload: Record<string, any> = {}) => {
+      onEventRef.current?.({
+        name,
+        timestamp: Date.now(),
+        shop: shop ? { storeId: shop.storeId, shopName: shop.shopName } : null,
+        payload,
+      });
+    },
+    [shop],
+  );
+
+  // cart 自动追踪
+  React.useEffect(() => {
+    if (!trackCart || !cartCtx) return;
+    return cartCtx.subscribe((c) => {
+      emit('cart_updated', {
+        cartId: c?.id,
+        totalQuantity: c?.totalQuantity,
+        totalAmount: c?.cost.totalAmount,
+      });
+    });
+  }, [trackCart, cartCtx, emit]);
+
+  return <Ctx.Provider value={{ emit }}>{children}</Ctx.Provider>;
+}
+
+export function useAnalytics(): AnalyticsContextValue {
+  const v = React.useContext(Ctx);
+  if (!v) {
+    // 没 Provider 时返回 noop（不 throw，便于组件可选嵌入）
+    return { emit: () => {} };
+  }
+  return v;
+}
+
+// ============================================================
+// 声明式事件组件
+// ============================================================
+
+function useEmitOnMount(name: string, payload: Record<string, any>) {
+  const { emit } = useAnalytics();
+  const payloadRef = React.useRef(payload);
+  payloadRef.current = payload;
+  React.useEffect(() => {
+    emit(name, payloadRef.current);
+    // 只 mount 时触发一次（路由切换会重新 mount）
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  return null;
+}
+
+function PageView(props: { path?: string; title?: string; [key: string]: any }) {
+  return useEmitOnMount('page_view', props);
+}
+
+function ProductView(props: { product: { id: string; handle?: string; title?: string }; [key: string]: any }) {
+  const { product, ...rest } = props;
+  return useEmitOnMount('product_view', {
+    ...rest,
+    productId: product.id,
+    productHandle: product.handle,
+    productTitle: product.title,
+  });
+}
+
+function CollectionView(props: { collection: { id: string; handle?: string }; [key: string]: any }) {
+  const { collection, ...rest } = props;
+  return useEmitOnMount('collection_view', {
+    ...rest,
+    collectionId: collection.id,
+    collectionHandle: collection.handle,
+  });
+}
+
+function SearchView(props: { query: string; results?: number }) {
+  return useEmitOnMount('search', { query: props.query, results: props.results });
+}
+
+function AddToCart(props: { variantId: string; quantity?: number; [key: string]: any }) {
+  const { variantId, quantity, ...rest } = props;
+  return useEmitOnMount('add_to_cart', {
+    ...rest,
+    variantId,
+    quantity: quantity ?? 1,
+  });
+}
+
+function CheckoutStart(props: { cart?: { id: string; totalQuantity?: number } }) {
+  return useEmitOnMount('checkout_start', {
+    cartId: props.cart?.id,
+    totalQuantity: props.cart?.totalQuantity,
+  });
+}
+
+function Purchase(props: { orderId: string; total: number; currencyCode: string; [key: string]: any }) {
+  return useEmitOnMount('purchase', props);
+}
+
+/** 命名空间导出，让用户写 <Analytics.PageView /> */
+export const Analytics = {
+  PageView,
+  ProductView,
+  CollectionView,
+  SearchView,
+  AddToCart,
+  CheckoutStart,
+  Purchase,
+};

package/src/components/CartProvider.tsx

@@ -0,0 +1,378 @@
+/**
+ * <CartProvider> + useCart()
+ *
+ * 接管 cart 全生命周期：
+ *   - 自动从 cookie 读取 cart_id 并 fetch
+ *   - 不存在则懒创建
+ *   - linesAdd / linesUpdate / linesRemove 全部带 optimistic update + 失败回滚
+ *   - subscribe(callback) 给外部（如 Analytics）订阅 cart 变化
+ *
+ * 用法：
+ *   <ShopProvider {...}>
+ *     <CartProvider>
+ *       <App />
+ *     </CartProvider>
+ *   </ShopProvider>
+ *
+ *   const { cart, status, linesAdd, linesUpdate, linesRemove } = useCart();
+ *
+ * 注意：必须套在 <ShopProvider> 内（依赖它的 storefrontAccessToken + apiUrl）。
+ */
+
+import * as React from 'react';
+import { useShop } from './ShopProvider';
+
+// ============================================================
+// Types
+// ============================================================
+
+export interface CartLineMerchandise {
+  id: string;
+  title?: string;
+  image?: { url: string; altText?: string | null; width?: number | null; height?: number | null };
+  price?: { amount: string; currencyCode: string };
+  product?: { title: string; handle: string };
+}
+
+export interface CartLine {
+  id: string;
+  quantity: number;
+  merchandise: CartLineMerchandise;
+  cost: { totalAmount: { amount: string; currencyCode: string } };
+}
+
+export interface Cart {
+  id: string;
+  totalQuantity: number;
+  checkoutUrl: string;
+  lines: { nodes: CartLine[] };
+  cost: {
+    subtotalAmount: { amount: string; currencyCode: string };
+    totalAmount: { amount: string; currencyCode: string };
+  };
+}
+
+export type CartStatus = 'uninitialized' | 'loading' | 'idle' | 'updating' | 'error';
+
+export interface CartUserError {
+  field?: string[] | null;
+  message: string;
+  code?: string;
+}
+
+export interface CartContextValue {
+  cart: Cart | null;
+  status: CartStatus;
+  error: string | null;
+  /** 加 line */
+  linesAdd: (lines: Array<{ merchandiseId: string; quantity?: number }>) => Promise<void>;
+  /** 更新数量（lineId, quantity）；quantity<=0 等价 remove */
+  linesUpdate: (lines: Array<{ id: string; quantity: number }>) => Promise<void>;
+  /** 删 line */
+  linesRemove: (lineIds: string[]) => Promise<void>;
+  /** 重新从服务端拉 cart */
+  refetch: () => Promise<void>;
+  /** 订阅 cart 变化（Analytics 用） */
+  subscribe: (listener: (cart: Cart | null) => void) => () => void;
+}
+
+const CartContext = React.createContext<CartContextValue | null>(null);
+
+// ============================================================
+// GraphQL
+// ============================================================
+
+const CART_FRAGMENT = /* GraphQL */ `
+  fragment CartParts on Cart {
+    id totalQuantity checkoutUrl
+    lines(first: 100) {
+      nodes {
+        id quantity
+        merchandise {
+          ... on ProductVariant {
+            id title
+            image { url altText width height }
+            price { amount currencyCode }
+            product { title handle }
+          }
+        }
+        cost { totalAmount { amount currencyCode } }
+      }
+    }
+    cost {
+      subtotalAmount { amount currencyCode }
+      totalAmount { amount currencyCode }
+    }
+  }
+`;
+
+const Q_GET_CART = CART_FRAGMENT + `
+  query GetCart($id: ID!) { cart(id: $id) { ...CartParts } }
+`;
+const M_CART_CREATE = CART_FRAGMENT + `
+  mutation Create($input: CartInput) {
+    cartCreate(input: $input) { cart { ...CartParts } userErrors { field message code } }
+  }
+`;
+const M_LINES_ADD = CART_FRAGMENT + `
+  mutation Add($cartId: ID!, $lines: [CartLineInput!]!) {
+    cartLinesAdd(cartId: $cartId, lines: $lines) { cart { ...CartParts } userErrors { field message code } }
+  }
+`;
+const M_LINES_UPDATE = CART_FRAGMENT + `
+  mutation Update($cartId: ID!, $lines: [CartLineUpdateInput!]!) {
+    cartLinesUpdate(cartId: $cartId, lines: $lines) { cart { ...CartParts } userErrors { field message code } }
+  }
+`;
+const M_LINES_REMOVE = CART_FRAGMENT + `
+  mutation Remove($cartId: ID!, $lineIds: [ID!]!) {
+    cartLinesRemove(cartId: $cartId, lineIds: $lineIds) { cart { ...CartParts } userErrors { field message code } }
+  }
+`;
+
+// ============================================================
+// cookie cart id
+// ============================================================
+
+const COOKIE_NAME = 'cart';
+
+function readCartIdFromCookie(): string | null {
+  if (typeof document === 'undefined') return null;
+  const m = document.cookie.match(new RegExp('(?:^|; )' + COOKIE_NAME + '=([^;]+)'));
+  if (!m) return null;
+  return `gid://shopbb/Cart/${decodeURIComponent(m[1])}`;
+}
+
+function saveCartIdToCookie(cartGid: string) {
+  if (typeof document === 'undefined') return;
+  const id = cartGid.replace(/^gid:\/\/shopbb\/Cart\//, '');
+  const oneYear = 365 * 24 * 60 * 60;
+  document.cookie = `${COOKIE_NAME}=${encodeURIComponent(id)}; path=/; max-age=${oneYear}; SameSite=Lax`;
+}
+
+// ============================================================
+// Provider
+// ============================================================
+
+export interface CartProviderProps {
+  children: React.ReactNode;
+  /** 加载完成后是否自动拉 cart。默认 true */
+  fetchOnMount?: boolean;
+}
+
+export function CartProvider({ children, fetchOnMount = true }: CartProviderProps) {
+  const shop = useShop();
+  const [cart, setCart] = React.useState<Cart | null>(null);
+  const [status, setStatus] = React.useState<CartStatus>('uninitialized');
+  const [error, setError] = React.useState<string | null>(null);
+  const listenersRef = React.useRef(new Set<(c: Cart | null) => void>());
+
+  const gql = React.useCallback(
+    async <T = any>(query: string, variables?: any): Promise<T> => {
+      const res = await fetch(shop.apiUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Storefront-Access-Token': shop.storefrontAccessToken,
+        },
+        body: JSON.stringify({ query, variables }),
+        credentials: 'include',
+      });
+      const json: any = await res.json();
+      if (json.errors) throw new Error(json.errors[0]?.message || 'GraphQL error');
+      return json.data;
+    },
+    [shop.apiUrl, shop.storefrontAccessToken],
+  );
+
+  const notifyListeners = React.useCallback((c: Cart | null) => {
+    for (const fn of listenersRef.current) fn(c);
+  }, []);
+
+  // 应用新 cart 数据（state + 订阅者）
+  const applyCart = React.useCallback(
+    (next: Cart | null) => {
+      setCart(next);
+      notifyListeners(next);
+    },
+    [notifyListeners],
+  );
+
+  // 保证有 cart_id，没有就创建
+  const ensureCartId = React.useCallback(async (): Promise<string> => {
+    const cookieCartId = readCartIdFromCookie();
+    if (cookieCartId) return cookieCartId;
+    const data = await gql<{ cartCreate: { cart: Cart; userErrors: CartUserError[] } }>(
+      M_CART_CREATE,
+      { input: { lines: [] } },
+    );
+    if (data.cartCreate.userErrors.length > 0) {
+      throw new Error(data.cartCreate.userErrors[0].message);
+    }
+    const newCart = data.cartCreate.cart;
+    saveCartIdToCookie(newCart.id);
+    applyCart(newCart);
+    return newCart.id;
+  }, [gql, applyCart]);
+
+  // 初始拉取
+  const refetch = React.useCallback(async () => {
+    setStatus('loading');
+    try {
+      const cookieCartId = readCartIdFromCookie();
+      if (!cookieCartId) {
+        applyCart(null);
+        setStatus('idle');
+        return;
+      }
+      const data = await gql<{ cart: Cart | null }>(Q_GET_CART, { id: cookieCartId });
+      applyCart(data.cart);
+      setStatus('idle');
+    } catch (err: any) {
+      setError(err?.message ?? String(err));
+      setStatus('error');
+    }
+  }, [gql, applyCart]);
+
+  React.useEffect(() => {
+    if (fetchOnMount && status === 'uninitialized') {
+      void refetch();
+    }
+  }, [fetchOnMount, status, refetch]);
+
+  // optimistic 包装
+  const runMutation = React.useCallback(
+    async <T,>(optimisticCart: Cart | null, mutator: () => Promise<{ cart: Cart; userErrors: CartUserError[] }>) => {
+      const prev = cart;
+      if (optimisticCart) applyCart(optimisticCart);
+      setStatus('updating');
+      try {
+        const result = await mutator();
+        if (result.userErrors && result.userErrors.length > 0) {
+          throw new Error(result.userErrors[0].message);
+        }
+        applyCart(result.cart);
+        setStatus('idle');
+        setError(null);
+      } catch (err: any) {
+        applyCart(prev); // 回滚
+        setError(err?.message ?? String(err));
+        setStatus('error');
+        throw err;
+      }
+    },
+    [cart, applyCart],
+  );
+
+  const linesAdd = React.useCallback(
+    async (lines: Array<{ merchandiseId: string; quantity?: number }>) => {
+      const cartId = await ensureCartId();
+      await runMutation(null, async () => {
+        const data = await gql<{ cartLinesAdd: { cart: Cart; userErrors: CartUserError[] } }>(
+          M_LINES_ADD,
+          {
+            cartId,
+            lines: lines.map((l) => ({ merchandiseId: l.merchandiseId, quantity: l.quantity ?? 1 })),
+          },
+        );
+        return data.cartLinesAdd;
+      });
+    },
+    [ensureCartId, runMutation, gql],
+  );
+
+  const linesUpdate = React.useCallback(
+    async (lines: Array<{ id: string; quantity: number }>) => {
+      // remove 走 remove
+      const toRemove = lines.filter((l) => l.quantity <= 0).map((l) => l.id);
+      const toUpdate = lines.filter((l) => l.quantity > 0);
+
+      // optimistic: 改 quantity
+      const optimistic =
+        cart != null
+          ? {
+              ...cart,
+              lines: {
+                ...cart.lines,
+                nodes: cart.lines.nodes
+                  .map((ln) => {
+                    const upd = toUpdate.find((l) => l.id === ln.id);
+                    return upd ? { ...ln, quantity: upd.quantity } : ln;
+                  })
+                  .filter((ln) => !toRemove.includes(ln.id)),
+              },
+            }
+          : null;
+
+      const cartId = await ensureCartId();
+      await runMutation(optimistic, async () => {
+        if (toRemove.length > 0) {
+          await gql(M_LINES_REMOVE, { cartId, lineIds: toRemove });
+        }
+        if (toUpdate.length === 0) {
+          const data = await gql<{ cart: Cart }>(Q_GET_CART, { id: cartId });
+          return { cart: data.cart!, userErrors: [] };
+        }
+        const data = await gql<{ cartLinesUpdate: { cart: Cart; userErrors: CartUserError[] } }>(
+          M_LINES_UPDATE,
+          { cartId, lines: toUpdate },
+        );
+        return data.cartLinesUpdate;
+      });
+    },
+    [cart, ensureCartId, runMutation, gql],
+  );
+
+  const linesRemove = React.useCallback(
+    async (lineIds: string[]) => {
+      const optimistic =
+        cart != null
+          ? {
+              ...cart,
+              lines: { ...cart.lines, nodes: cart.lines.nodes.filter((l) => !lineIds.includes(l.id)) },
+            }
+          : null;
+
+      const cartId = await ensureCartId();
+      await runMutation(optimistic, async () => {
+        const data = await gql<{ cartLinesRemove: { cart: Cart; userErrors: CartUserError[] } }>(
+          M_LINES_REMOVE,
+          { cartId, lineIds },
+        );
+        return data.cartLinesRemove;
+      });
+    },
+    [cart, ensureCartId, runMutation, gql],
+  );
+
+  const subscribe = React.useCallback((listener: (c: Cart | null) => void) => {
+    listenersRef.current.add(listener);
+    return () => {
+      listenersRef.current.delete(listener);
+    };
+  }, []);
+
+  const value: CartContextValue = React.useMemo(
+    () => ({ cart, status, error, linesAdd, linesUpdate, linesRemove, refetch, subscribe }),
+    [cart, status, error, linesAdd, linesUpdate, linesRemove, refetch, subscribe],
+  );
+
+  return <CartContext.Provider value={value}>{children}</CartContext.Provider>;
+}
+
+/**
+ * 拿 cart context。Provider 外 throw。
+ */
+export function useCart(): CartContextValue {
+  const v = React.useContext(CartContext);
+  if (!v) throw new Error('useCart must be used inside <CartProvider>');
+  return v;
+}
+
+/**
+ * 非 throw 版本：Provider 外返回 null。
+ * 给可选 fallback 用，比如 <AddToCartButton> 在没 Provider 时退化到 props.onAdd。
+ */
+export function useCartOptional(): CartContextValue | null {
+  return React.useContext(CartContext);
+}

package/src/components/Money.tsx

@@ -14,6 +14,7 @@
  */
 
 import * as React from 'react';
+import { useShopOptional } from './ShopProvider';
 
 export interface MoneyData {
   amount: string;
@@ -64,7 +65,12 @@ export function Money(props: MoneyProps) {
   } = props;
 
   const Tag: any = as || 'span';
-  const locale = localeProp || DEFAULT_LOCALE_BY_CURRENCY[data.currencyCode] || 'en-US';
+  const shop = useShopOptional();
+  const locale =
+    localeProp ||
+    shop?.locale ||
+    DEFAULT_LOCALE_BY_CURRENCY[data.currencyCode] ||
+    'en-US';
   const amount = Number(data.amount);
 
   let formatted: string;