@shopbb/helium 0.3.1 → 0.5.0

package/src/components/DiscountProvider.tsx

@@ -0,0 +1,390 @@
+/**
+ * <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 上的折扣分配明细。
+   * W5 起：cart 上最多一张券（自动选最佳 / 买家手动选）。
+   * 数组语义保留兼容（未来可能允许多张叠加）。
+   */
+  cartAllocations: CartDiscountAllocation[];
+  /** 当前应用的 claim ID（W5），null = 无折扣或买家未登录 */
+  appliedClaimId: string | null;
+  /** 错误 */
+  error: string | null;
+
+  // 操作
+  claim: (code: string) => Promise<{ claim?: DiscountClaim; 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 上的折扣（服务端算好的） -----
+  const cartAllocations = cartCtx?.cart && (cartCtx.cart as any).discountAllocations
+    ? (cartCtx.cart as any).discountAllocations as CartDiscountAllocation[]
+    : [];
+  // W5: 服务端的 appliedDiscountClaim（哪张被选中应用了）
+  const appliedClaimId: string | null = cartCtx?.cart && (cartCtx.cart as any).appliedDiscountClaim?.claimId
+    ? (cartCtx.cart as any).appliedDiscountClaim.claimId
+    : null;
+
+  const value: DiscountContextValue = React.useMemo(
+    () => ({
+      publicDiscounts, publicDiscountsStatus,
+      myDiscounts, myDiscountsStatus,
+      cartAllocations,
+      appliedClaimId,
+      error,
+      claim,
+      refetchMyDiscounts, refetchPublicDiscounts,
+    }),
+    [
+      publicDiscounts, publicDiscountsStatus,
+      myDiscounts, myDiscountsStatus,
+      cartAllocations, appliedClaimId, error,
+      claim,
+      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/DiscountSelector.tsx

@@ -0,0 +1,220 @@
+/**
+ * <DiscountSelector>
+ *
+ * Cart 上的优惠券选择器 — 卡片式 UI，对齐拼多多 / 京东体验。
+ *
+ * 行为：
+ *   - 默认显示当前应用的券（服务端自动选了最佳，或买家显式选的）
+ *   - 点"切换"打开抽屉/弹窗，列出该买家所有可用券（从 useDiscounts().myDiscounts）
+ *   - 选另一张 → 调 cartDiscountSelect mutation
+ *   - 点"不使用优惠券" → cartDiscountClear
+ *
+ * 未登录买家：渲染"登录后享受优惠"提示。
+ *
+ * 设计目标：
+ *   - 这是 helium "脚手架" 的卡片式实现。商家可以替换为抽屉式 / 弹窗式自定义 UI。
+ *   - 商家也可以直接用 useDiscounts() 自己渲染（提供 hook-only 路径）。
+ */
+
+import * as React from 'react';
+import { useDiscounts, type DiscountClaim } from './DiscountProvider';
+import { useCart } from './CartProvider';
+import { useShop } from './ShopProvider';
+import { useAnalytics } from './AnalyticsProvider';
+import { Money } from './Money';
+
+export interface DiscountSelectorProps {
+  className?: string;
+  /** 未登录时显示的内容；不传则显示默认 */
+  unauthenticatedFallback?: React.ReactNode;
+  /** 自定义渲染 */
+  renderApplied?: (props: { code: string | null; title: string; amount: { amount: string; currencyCode: string }; onChange: () => void; onClear: () => void }) => React.ReactNode;
+}
+
+export function DiscountSelector(props: DiscountSelectorProps) {
+  const { className, unauthenticatedFallback, renderApplied } = props;
+  const { myDiscounts, myDiscountsStatus, cartAllocations } = useDiscounts();
+  const { cart, refetch: refetchCart } = useCart();
+  const shop = useShop();
+  const analytics = useAnalytics();
+
+  const [open, setOpen] = React.useState(false);
+  const [pending, setPending] = React.useState(false);
+
+  // 服务端已经决定了 cart 上是哪张券
+  const appliedAlloc = cartAllocations[0];
+  const appliedClaimId = (cart as any)?.appliedDiscountClaim?.claimId ?? null;
+  const appliedTitle = (cart as any)?.appliedDiscountClaim?.title ?? appliedAlloc?.title;
+  const appliedCode = (cart as any)?.appliedDiscountClaim?.code ?? appliedAlloc?.code;
+
+  const callSelectMutation = async (claimId: string | null) => {
+    if (!cart) return;
+    setPending(true);
+    try {
+      const token = (typeof localStorage !== 'undefined') ? (localStorage.getItem('shopbb:buyer_token') || localStorage.getItem('shopflare:buyer_token')) : null;
+      const mutation = claimId
+        ? `mutation S($id: ID!, $c: ID!) { cartDiscountSelect(cartId: $id, claimId: $c) { cart { id } userErrors { message } } }`
+        : `mutation C($id: ID!) { cartDiscountClear(cartId: $id) { cart { id } userErrors { message } } }`;
+      const variables: any = { id: cart.id };
+      if (claimId) variables.c = claimId;
+      const res = await fetch(shop.apiUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Storefront-Access-Token': shop.storefrontAccessToken,
+          ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: JSON.stringify({ query: mutation, variables }),
+        credentials: 'include',
+      });
+      await res.json();
+      // 重新拉 cart 让 UI 更新（拿到新的 discountAllocations）
+      await refetchCart();
+    } finally {
+      setPending(false);
+      setOpen(false);
+    }
+  };
+
+  // 未登录
+  if (myDiscountsStatus === 'unauthenticated') {
+    return unauthenticatedFallback !== undefined ? <>{unauthenticatedFallback}</> : (
+      <div data-discount-selector data-unauth className={className}>
+        <span>登录后可使用优惠券</span>
+        <a href="/login?next=/cart">去登录</a>
+      </div>
+    );
+  }
+
+  if (myDiscountsStatus === 'loading') {
+    return <div data-discount-selector data-loading className={className}>加载优惠券…</div>;
+  }
+
+  const availableClaims = myDiscounts.filter((c) => !c.isExpired && c.remainingUses > 0);
+
+  if (availableClaims.length === 0) {
+    return (
+      <div data-discount-selector data-no-discount className={className}>
+        <span>暂无可用优惠券</span>
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <div data-discount-selector className={className}>
+        {appliedClaimId ? (
+          renderApplied ? renderApplied({
+            code: appliedCode ?? null,
+            title: appliedTitle ?? '',
+            amount: appliedAlloc?.discountedAmount ?? { amount: '0', currencyCode: 'CNY' },
+            onChange: () => setOpen(true),
+            onClear: () => callSelectMutation(null),
+          }) : (
+            <div data-applied>
+              <div data-info>
+                <span data-label>已使用</span>
+                <strong data-title>{appliedTitle}</strong>
+                {appliedAlloc && (
+                  <span data-amount>− <Money data={{ amount: appliedAlloc.discountedAmount.amount, currencyCode: appliedAlloc.discountedAmount.currencyCode }} /></span>
+                )}
+              </div>
+              <div data-actions>
+                <button type="button" onClick={() => setOpen(true)} disabled={pending}>切换</button>
+                <button type="button" onClick={() => callSelectMutation(null)} disabled={pending} data-clear>不使用</button>
+              </div>
+            </div>
+          )
+        ) : (
+          <div data-empty-applied>
+            <div data-info>
+              <span data-label>有 {availableClaims.length} 张可用优惠券</span>
+            </div>
+            <button type="button" onClick={() => setOpen(true)} disabled={pending}>选择</button>
+          </div>
+        )}
+      </div>
+
+      {open && (
+        <DiscountPickerSheet
+          claims={availableClaims}
+          currentClaimId={appliedClaimId}
+          onSelect={(claimId) => {
+            analytics.emit('discount_select', { claimId });
+            callSelectMutation(claimId);
+          }}
+          onClose={() => setOpen(false)}
+          pending={pending}
+        />
+      )}
+    </>
+  );
+}
+
+/**
+ * 抽屉式选券面板。
+ * Demo 实现为屏底固定面板；商家可以替换为 modal / 抽屉等。
+ */
+function DiscountPickerSheet({
+  claims, currentClaimId, onSelect, onClose, pending,
+}: {
+  claims: DiscountClaim[];
+  currentClaimId: string | null;
+  onSelect: (claimId: string) => void;
+  onClose: () => void;
+  pending: boolean;
+}) {
+  return (
+    <div data-discount-picker-overlay onClick={onClose}>
+      <div data-discount-picker-sheet onClick={(e) => e.stopPropagation()}>
+        <div data-sheet-header>
+          <h3>选择优惠券</h3>
+          <button type="button" onClick={onClose} data-sheet-close>×</button>
+        </div>
+        <div data-sheet-list>
+          {claims.map((c) => {
+            const id = c.id.replace(/^gid:\/\/shopbb\/DiscountClaim\//, '');
+            const isCurrent = currentClaimId === id;
+            return (
+              <button
+                key={c.id}
+                type="button"
+                data-claim-card
+                data-current={isCurrent ? '' : undefined}
+                onClick={() => onSelect(id)}
+                disabled={pending}
+              >
+                <div data-claim-left>
+                  <div data-claim-value>{formatValue(c)}</div>
+                  {c.discount.minSubtotal && (
+                    <div data-claim-min>
+                      满 <Money data={{ amount: c.discount.minSubtotal.amount, currencyCode: c.discount.minSubtotal.currencyCode }} /> 可用
+                    </div>
+                  )}
+                </div>
+                <div data-claim-right>
+                  <div data-claim-title>{c.discount.title}</div>
+                  {c.discount.code && <div data-claim-code>{c.discount.code}</div>}
+                  {c.expiresAt && (
+                    <div data-claim-expiry>{new Date(c.expiresAt).toLocaleDateString('zh-CN')} 过期</div>
+                  )}
+                </div>
+                {isCurrent && <span data-claim-current-tag>当前使用</span>}
+              </button>
+            );
+          })}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function formatValue(c: DiscountClaim): string {
+  if (c.discount.valueType === 'PERCENTAGE' && c.discount.valuePercentage != null) {
+    return `${100 - c.discount.valuePercentage} 折`;
+  }
+  if (c.discount.valueType === 'FIXED_AMOUNT' && c.discount.valueAmount) {
+    return `− ¥${c.discount.valueAmount.amount}`;
+  }
+  return '免运费';
+}

package/src/components/index.ts

@@ -69,3 +69,64 @@ 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 {
+  AppliedDiscountList,
+  ClaimableDiscountList,
+  DiscountClaimButton,
+  MyDiscountList,
+} from './DiscountComponents';
+export type {
+  AppliedDiscountListProps,
+  ClaimableDiscountListProps,
+  DiscountClaimButtonProps,
+  MyDiscountListProps,
+} from './DiscountComponents';
+
+export { DiscountSelector } from './DiscountSelector';
+export type { DiscountSelectorProps } from './DiscountSelector';