@shopbb/helium 0.3.0 → 0.4.0

package/src/components/DiscountProvider.tsx

@@ -0,0 +1,455 @@
+/**
+ * <DiscountProvider> + useDiscounts() + useProductDiscounts()
+ *
+ * 优惠券完整能力：
+ *   - publicDiscounts: 公开可领的券（storefront 首页 / cart 展示）
+ *   - myDiscounts: 我领过的有效券（卡包）
+ *   - claim(code): 领取
+ *   - cart 上的折扣：appliedToCart / applyToCart / removeFromCart
+ *   - bestApplicableForCart: 当前 cart 最大可省（哪张最划算）
+ *
+ * 内部走 Storefront GraphQL + Customer Account GraphQL。
+ */
+
+import * as React from 'react';
+import { useShop } from './ShopProvider';
+import { useCartOptional } from './CartProvider';
+
+// ============================================================
+// Types
+// ============================================================
+
+export type DiscountValueType = 'PERCENTAGE' | 'FIXED_AMOUNT' | 'FREE_SHIPPING';
+
+export interface DiscountValuePercentage { __typename: 'DiscountPercentage'; percentage: number; }
+export interface DiscountValueAmount { __typename: 'DiscountAmount'; amount: { amount: string; currencyCode: string }; }
+export interface DiscountValueFreeShipping { __typename: 'DiscountFreeShipping'; freeShipping: boolean; }
+
+export interface Discount {
+  id: string;
+  code: string | null;
+  title: string;
+  description: string | null;
+  valueType: DiscountValueType;
+  value: DiscountValuePercentage | DiscountValueAmount | DiscountValueFreeShipping;
+  appliesTo: 'ALL' | 'PRODUCTS' | 'COLLECTIONS';
+  minSubtotal: { amount: string; currencyCode: string } | null;
+  startsAt: string | null;
+  endsAt: string | null;
+  bannerImage: { url: string; altText?: string | null } | null;
+  distribution: 'PUBLIC' | 'MANUAL' | 'AUTO';
+}
+
+export interface DiscountClaim {
+  id: string;
+  claimedAt: string;
+  usedCount: number;
+  remainingUses: number;
+  expiresAt: string | null;
+  isExpired: boolean;
+  discount: {
+    id: string;
+    code: string | null;
+    title: string;
+    description: string | null;
+    valueType: DiscountValueType;
+    valuePercentage: number | null;
+    valueAmount: { amount: string; currencyCode: string } | null;
+    minSubtotal: { amount: string; currencyCode: string } | null;
+    endsAt: string | null;
+    bannerImage: string | null;
+  };
+}
+
+export interface CartDiscountCode {
+  code: string;
+  applicable: boolean;
+}
+
+export interface CartDiscountAllocation {
+  discountedAmount: { amount: string; currencyCode: string };
+  targetType: 'CART' | 'LINE';
+  targetId: string | null;
+  title: string;
+  code: string | null;
+}
+
+export interface DiscountUserError {
+  field?: string[];
+  code?: string;
+  message: string;
+}
+
+export interface DiscountContextValue {
+  /** 公开可领的券 */
+  publicDiscounts: Discount[];
+  publicDiscountsStatus: 'idle' | 'loading' | 'error';
+  /** 我领过的有效券 */
+  myDiscounts: DiscountClaim[];
+  myDiscountsStatus: 'unauthenticated' | 'idle' | 'loading' | 'error';
+  /** 当前 cart 上应用的码 */
+  appliedToCart: CartDiscountCode[];
+  /** 当前 cart 上的折扣分配明细 */
+  cartAllocations: CartDiscountAllocation[];
+  /** 当前 cart 上最大可省（计算了用户已领但未应用的券） */
+  bestApplicableForCart: { discount: DiscountClaim; estimatedAmount: number } | null;
+  /** 错误 */
+  error: string | null;
+
+  // 操作
+  claim: (code: string) => Promise<{ claim?: DiscountClaim; userErrors: DiscountUserError[] }>;
+  applyToCart: (code: string) => Promise<{ userErrors: DiscountUserError[] }>;
+  removeFromCart: (code: string) => Promise<{ userErrors: DiscountUserError[] }>;
+  refetchMyDiscounts: () => Promise<void>;
+  refetchPublicDiscounts: () => Promise<void>;
+}
+
+const Ctx = React.createContext<DiscountContextValue | null>(null);
+
+// ============================================================
+// Provider
+// ============================================================
+
+export interface DiscountProviderProps {
+  children: React.ReactNode;
+  /** 自动 fetch publicDiscounts；默认 true */
+  fetchPublicOnMount?: boolean;
+  /** 自动 fetch myDiscounts（登录买家）；默认 true */
+  fetchMyOnMount?: boolean;
+  /** 自定义 token */
+  tokenProvider?: () => string | null;
+}
+
+const DEFAULT_TOKEN_KEY = 'shopbb:buyer_token';
+
+export function DiscountProvider(props: DiscountProviderProps) {
+  const { children, fetchPublicOnMount = true, fetchMyOnMount = true, tokenProvider } = props;
+  const shop = useShop();
+  const cartCtx = useCartOptional();
+
+  const [publicDiscounts, setPublicDiscounts] = React.useState<Discount[]>([]);
+  const [publicDiscountsStatus, setPublicDiscountsStatus] = React.useState<'idle' | 'loading' | 'error'>('idle');
+  const [myDiscounts, setMyDiscounts] = React.useState<DiscountClaim[]>([]);
+  const [myDiscountsStatus, setMyDiscountsStatus] = React.useState<'unauthenticated' | 'idle' | 'loading' | 'error'>('idle');
+  const [error, setError] = React.useState<string | null>(null);
+
+  const customerEndpoint = React.useMemo(() => {
+    try {
+      const u = new URL(shop.apiUrl);
+      return `${u.origin}/customer/api/2026-04/graphql`;
+    } catch {
+      return shop.apiUrl;
+    }
+  }, [shop.apiUrl]);
+
+  const getToken = React.useCallback(() => {
+    if (tokenProvider) return tokenProvider();
+    if (typeof localStorage === 'undefined') return null;
+    return localStorage.getItem(DEFAULT_TOKEN_KEY) || localStorage.getItem('shopflare:buyer_token');
+  }, [tokenProvider]);
+
+  const storefrontGql = React.useCallback(
+    async <T = any>(query: string, variables?: any): Promise<{ data?: T; errors?: any[] }> => {
+      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',
+      });
+      return res.json();
+    },
+    [shop.apiUrl, shop.storefrontAccessToken],
+  );
+
+  const customerGql = React.useCallback(
+    async <T = any>(query: string, variables?: any): Promise<{ data?: T; errors?: any[] }> => {
+      const token = getToken();
+      if (!token) throw new Error('not authenticated');
+      const res = await fetch(customerEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ query, variables }),
+      });
+      return res.json();
+    },
+    [customerEndpoint, getToken],
+  );
+
+  // ----- public discounts -----
+  const refetchPublicDiscounts = React.useCallback(async () => {
+    setPublicDiscountsStatus('loading');
+    try {
+      const result = await storefrontGql<{ publicDiscounts: { nodes: Discount[] } }>(
+        `query { publicDiscounts(first: 50) {
+           nodes {
+             id code title description distribution appliesTo
+             valueType
+             value {
+               __typename
+               ... on DiscountPercentage { percentage }
+               ... on DiscountAmount { amount { amount currencyCode } }
+               ... on DiscountFreeShipping { freeShipping }
+             }
+             minSubtotal { amount currencyCode }
+             startsAt endsAt
+             bannerImage { url altText }
+           }
+         } }`,
+      );
+      if (result.errors?.length) throw new Error(result.errors[0].message);
+      setPublicDiscounts(result.data?.publicDiscounts?.nodes ?? []);
+      setPublicDiscountsStatus('idle');
+    } catch (e: any) {
+      setError(e?.message);
+      setPublicDiscountsStatus('error');
+    }
+  }, [storefrontGql]);
+
+  // ----- my discounts -----
+  const refetchMyDiscounts = React.useCallback(async () => {
+    const token = getToken();
+    if (!token) {
+      setMyDiscountsStatus('unauthenticated');
+      setMyDiscounts([]);
+      return;
+    }
+    setMyDiscountsStatus('loading');
+    try {
+      const result = await customerGql<{ customer: { discountClaims: { nodes: DiscountClaim[] } } | null }>(
+        `query { customer { discountClaims(first: 50) {
+           nodes {
+             id claimedAt usedCount remainingUses expiresAt isExpired
+             discount {
+               id code title description
+               valueType valuePercentage
+               valueAmount { amount currencyCode }
+               minSubtotal { amount currencyCode }
+               endsAt bannerImage
+             }
+           }
+         } } }`,
+      );
+      if (result.errors?.length) throw new Error(result.errors[0].message);
+      setMyDiscounts(result.data?.customer?.discountClaims?.nodes ?? []);
+      setMyDiscountsStatus('idle');
+    } catch (e: any) {
+      setError(e?.message);
+      setMyDiscountsStatus('error');
+    }
+  }, [customerGql, getToken]);
+
+  React.useEffect(() => {
+    if (fetchPublicOnMount) void refetchPublicDiscounts();
+  }, [fetchPublicOnMount, refetchPublicDiscounts]);
+
+  React.useEffect(() => {
+    if (fetchMyOnMount) void refetchMyDiscounts();
+  }, [fetchMyOnMount, refetchMyDiscounts]);
+
+  // ----- claim -----
+  const claim = React.useCallback(
+    async (code: string) => {
+      try {
+        const result = await customerGql<{ discountClaim: { discountClaim: DiscountClaim | null; userErrors: DiscountUserError[] } }>(
+          `mutation C($code: String!) {
+             discountClaim(code: $code) {
+               discountClaim {
+                 id claimedAt usedCount remainingUses expiresAt isExpired
+                 discount {
+                   id code title valueType valuePercentage
+                   valueAmount { amount currencyCode }
+                   minSubtotal { amount currencyCode }
+                 }
+               }
+               userErrors { field code message }
+             }
+           }`,
+          { code },
+        );
+        if (result.errors?.length) throw new Error(result.errors[0].message);
+        await refetchMyDiscounts();
+        const payload = result.data!.discountClaim;
+        return { claim: payload.discountClaim ?? undefined, userErrors: payload.userErrors };
+      } catch (e: any) {
+        return { userErrors: [{ code: 'NETWORK_ERROR', message: e?.message ?? String(e) }] };
+      }
+    },
+    [customerGql, refetchMyDiscounts],
+  );
+
+  // ----- cart apply / remove -----
+  const appliedToCart = cartCtx?.cart && (cartCtx.cart as any).discountCodes ? (cartCtx.cart as any).discountCodes as CartDiscountCode[] : [];
+  const cartAllocations = cartCtx?.cart && (cartCtx.cart as any).discountAllocations ? (cartCtx.cart as any).discountAllocations as CartDiscountAllocation[] : [];
+
+  const applyCodes = React.useCallback(
+    async (codes: string[]) => {
+      if (!cartCtx?.cart) return { userErrors: [{ code: 'NO_CART', message: 'cart 不存在' }] };
+      const result = await storefrontGql<{ cartDiscountCodesUpdate: { cart: any; userErrors: DiscountUserError[] } }>(
+        `mutation U($id: ID!, $codes: [String!]!) {
+           cartDiscountCodesUpdate(cartId: $id, discountCodes: $codes) {
+             cart { id }
+             userErrors { field code message }
+           }
+         }`,
+        { id: cartCtx.cart.id, codes },
+      );
+      if (result.errors?.length) {
+        return { userErrors: [{ code: 'NETWORK_ERROR', message: result.errors[0].message }] };
+      }
+      // 刷 cart（拉新的 discountCodes / allocations）
+      await cartCtx.refetch();
+      return { userErrors: result.data!.cartDiscountCodesUpdate.userErrors };
+    },
+    [cartCtx, storefrontGql],
+  );
+
+  const applyToCart = React.useCallback(
+    async (code: string) => {
+      const existing = appliedToCart.map((d) => d.code);
+      if (existing.includes(code.toUpperCase())) return { userErrors: [] };
+      return applyCodes([...existing, code.toUpperCase()]);
+    },
+    [appliedToCart, applyCodes],
+  );
+
+  const removeFromCart = React.useCallback(
+    async (code: string) => {
+      const next = appliedToCart.map((d) => d.code).filter((c) => c !== code.toUpperCase());
+      return applyCodes(next);
+    },
+    [appliedToCart, applyCodes],
+  );
+
+  // ----- best applicable for cart -----
+  const bestApplicableForCart = React.useMemo(() => {
+    if (!cartCtx?.cart || myDiscounts.length === 0) return null;
+    const subtotalStr = (cartCtx.cart as any).cost?.subtotalAmount?.amount;
+    const subtotal = Number(subtotalStr || 0);
+    if (subtotal <= 0) return null;
+
+    const currentApplied = new Set(appliedToCart.map((d) => d.code));
+
+    let best: { discount: DiscountClaim; estimatedAmount: number } | null = null;
+    for (const claimed of myDiscounts) {
+      const d = claimed.discount;
+      if (!d.code || claimed.isExpired) continue;
+      if (currentApplied.has(d.code)) continue;
+      // 门槛
+      if (d.minSubtotal && Number(d.minSubtotal.amount) > subtotal) continue;
+      // 估算折扣
+      let amount = 0;
+      if (d.valueType === 'PERCENTAGE' && d.valuePercentage != null) {
+        amount = Math.floor(subtotal * (d.valuePercentage / 100) * 100) / 100;
+      } else if (d.valueType === 'FIXED_AMOUNT' && d.valueAmount) {
+        amount = Math.min(Number(d.valueAmount.amount), subtotal);
+      }
+      if (amount > 0 && (best == null || amount > best.estimatedAmount)) {
+        best = { discount: claimed, estimatedAmount: amount };
+      }
+    }
+    return best;
+  }, [cartCtx, myDiscounts, appliedToCart]);
+
+  const value: DiscountContextValue = React.useMemo(
+    () => ({
+      publicDiscounts, publicDiscountsStatus,
+      myDiscounts, myDiscountsStatus,
+      appliedToCart, cartAllocations,
+      bestApplicableForCart,
+      error,
+      claim, applyToCart, removeFromCart,
+      refetchMyDiscounts, refetchPublicDiscounts,
+    }),
+    [
+      publicDiscounts, publicDiscountsStatus,
+      myDiscounts, myDiscountsStatus,
+      appliedToCart, cartAllocations,
+      bestApplicableForCart, error,
+      claim, applyToCart, removeFromCart,
+      refetchMyDiscounts, refetchPublicDiscounts,
+    ],
+  );
+
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+}
+
+export function useDiscounts(): DiscountContextValue {
+  const v = React.useContext(Ctx);
+  if (!v) throw new Error('useDiscounts must be used inside <DiscountProvider>');
+  return v;
+}
+
+export function useDiscountsOptional(): DiscountContextValue | null {
+  return React.useContext(Ctx);
+}
+
+// ============================================================
+// useProductDiscounts(handle) — 商品页用
+// ============================================================
+
+export function useProductDiscounts(productHandle: string | null | undefined): {
+  discounts: Discount[];
+  loading: boolean;
+  error: string | null;
+} {
+  const shop = useShop();
+  const [discounts, setDiscounts] = React.useState<Discount[]>([]);
+  const [loading, setLoading] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    if (!productHandle) {
+      setDiscounts([]);
+      return;
+    }
+    let cancelled = false;
+    setLoading(true);
+    (async () => {
+      try {
+        const res = await fetch(shop.apiUrl, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'X-Storefront-Access-Token': shop.storefrontAccessToken,
+          },
+          body: JSON.stringify({
+            query: `query P($h: String!) {
+               productDiscounts(productHandle: $h) {
+                 id code title description
+                 valueType
+                 value {
+                   __typename
+                   ... on DiscountPercentage { percentage }
+                   ... on DiscountAmount { amount { amount currencyCode } }
+                   ... on DiscountFreeShipping { freeShipping }
+                 }
+                 minSubtotal { amount currencyCode }
+                 endsAt
+                 bannerImage { url }
+               }
+             }`,
+            variables: { h: productHandle },
+          }),
+          credentials: 'include',
+        });
+        const r: any = await res.json();
+        if (cancelled) return;
+        if (r.errors?.length) {
+          setError(r.errors[0].message);
+        } else {
+          setDiscounts(r.data?.productDiscounts ?? []);
+        }
+      } catch (e: any) {
+        if (!cancelled) setError(e?.message);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => { cancelled = true; };
+  }, [productHandle, shop.apiUrl, shop.storefrontAccessToken]);
+
+  return { discounts, loading, error };
+}

package/src/components/Money.tsx

@@ -43,53 +43,70 @@ export interface MoneyProps extends React.HTMLAttributes<HTMLElement> {
   measurement?: MoneyMeasurement;
 }
 
-// currencyCode → 默认 locale 推断
-const DEFAULT_LOCALE_BY_CURRENCY: Record<string, string> = {
-  CNY: 'zh-CN',
-  USD: 'en-US',
-  EUR: 'de-DE',
-  GBP: 'en-GB',
-  JPY: 'ja-JP',
-  KRW: 'ko-KR',
+/**
+ * currency → symbol。手写一张表，不用 Intl.NumberFormat —— 因为它在 Cloudflare Workers V8
+ * 和浏览器 V8 之间输出可能不同（货币符号位置、本地化分隔符），导致 SSR hydration mismatch。
+ *
+ * Shopify Hydrogen 的 <Money> 用同款手写方案，原因相同。
+ */
+const CURRENCY_SYMBOL: Record<string, string> = {
+  CNY: '¥',
+  USD: '$',
+  EUR: '€',
+  GBP: '£',
+  JPY: '¥',
+  HKD: 'HK$',
+  KRW: '₩',
 };
 
+/**
+ * 按 1000 分组加 thousand-separator。
+ * 中文/英文 locale 都是逗号；其他 locale 暂用逗号（如需 . 分隔，加 locale 表）。
+ */
+function formatAmount(amount: number, minDecimals: number, maxDecimals: number): string {
+  if (!Number.isFinite(amount)) return '0';
+  const negative = amount < 0;
+  const abs = Math.abs(amount);
+  // 强制小数位数
+  const fixed = abs.toFixed(maxDecimals);
+  const [intPart, decPart = ''] = fixed.split('.');
+  // 加千分位
+  const intWithSep = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  // 去掉多余的尾零（保留最低 minDecimals 位）
+  let trimmedDec = decPart;
+  while (trimmedDec.length > minDecimals && trimmedDec.endsWith('0')) {
+    trimmedDec = trimmedDec.slice(0, -1);
+  }
+  const out = trimmedDec ? `${intWithSep}.${trimmedDec}` : intWithSep;
+  return negative ? `-${out}` : out;
+}
+
 export function Money(props: MoneyProps) {
   const {
     data,
     withoutCurrency,
     withoutTrailingZeros,
-    locale: localeProp,
+    locale: _localeProp,
     as,
     measurement,
     ...rest
   } = props;
 
   const Tag: any = as || 'span';
-  const shop = useShopOptional();
-  const locale =
-    localeProp ||
-    shop?.locale ||
-    DEFAULT_LOCALE_BY_CURRENCY[data.currencyCode] ||
-    'en-US';
+  // locale 现在不影响输出（避免 SSR 不一致）。保留 prop 给未来可能扩展。
   const amount = Number(data.amount);
+  const minDec = withoutTrailingZeros && Number.isInteger(amount) ? 0 : 2;
+  const numStr = formatAmount(amount, minDec, 2);
+  const symbol = CURRENCY_SYMBOL[data.currencyCode];
 
   let formatted: string;
-  try {
-    const opts: Intl.NumberFormatOptions = withoutCurrency
-      ? {
-          minimumFractionDigits: withoutTrailingZeros && Number.isInteger(amount) ? 0 : 2,
-          maximumFractionDigits: 2,
-        }
-      : {
-          style: 'currency',
-          currency: data.currencyCode,
-          minimumFractionDigits: withoutTrailingZeros && Number.isInteger(amount) ? 0 : 2,
-          maximumFractionDigits: 2,
-        };
-    formatted = new Intl.NumberFormat(locale, opts).format(amount);
-  } catch {
-    // Fallback：Intl 不支持的 currencyCode
-    formatted = withoutCurrency ? amount.toFixed(2) : `${data.currencyCode} ${amount.toFixed(2)}`;
+  if (withoutCurrency) {
+    formatted = numStr;
+  } else if (symbol) {
+    formatted = `${symbol}${numStr}`;
+  } else {
+    // 未识别 currency code: 用 "USD 99.00" 形式
+    formatted = `${data.currencyCode} ${numStr}`;
   }
 
   // measurement suffix（unit price）

package/src/components/index.ts

@@ -69,3 +69,65 @@ export type {
   VariantSelectorRenderProps,
   VariantOption,
 } from './VariantSelector';
+
+// 地址簿（W4a）
+export {
+  AddressBookProvider,
+  useAddressBook,
+  useAddressBookOptional,
+} from './AddressBookProvider';
+export type {
+  Address,
+  AddressInput,
+  AddressBookStatus,
+  AddressBookUserError,
+  AddressBookContextValue,
+  AddressBookProviderProps,
+} from './AddressBookProvider';
+
+export { AddressList } from './AddressList';
+export type { AddressListProps, AddressListItemActions } from './AddressList';
+
+export { AddressForm } from './AddressForm';
+export type { AddressFormProps, AddressFormI18n } from './AddressForm';
+
+export { AddressPicker } from './AddressPicker';
+export type { AddressPickerProps } from './AddressPicker';
+
+// 优惠券（W4b）
+export {
+  DiscountProvider,
+  useDiscounts,
+  useDiscountsOptional,
+  useProductDiscounts,
+} from './DiscountProvider';
+export type {
+  Discount,
+  DiscountClaim,
+  DiscountValueType,
+  DiscountValuePercentage,
+  DiscountValueAmount,
+  DiscountValueFreeShipping,
+  CartDiscountCode,
+  CartDiscountAllocation,
+  DiscountUserError,
+  DiscountContextValue,
+  DiscountProviderProps,
+} from './DiscountProvider';
+
+export {
+  DiscountCodeInput,
+  AppliedDiscountList,
+  BestDiscountHint,
+  ClaimableDiscountList,
+  DiscountClaimButton,
+  MyDiscountList,
+} from './DiscountComponents';
+export type {
+  DiscountCodeInputProps,
+  AppliedDiscountListProps,
+  BestDiscountHintProps,
+  ClaimableDiscountListProps,
+  DiscountClaimButtonProps,
+  MyDiscountListProps,
+} from './DiscountComponents';