@shopbb/helium 0.6.3 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopbb/helium",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "shopbb storefront framework — components, React SSR, GraphQL client, cart handler, cache for Cloudflare Workers",
   "license": "MIT",
   "type": "module",
@@ -49,15 +49,8 @@
   "repository": "https://github.com/shopbb/shopbb",
   "peerDependencies": {
     "react": ">=18",
-    "react-dom": ">=18"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    },
-    "react-dom": {
-      "optional": true
-    }
+    "react-dom": ">=18",
+    "react-router": ">=7"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20240117.0",
@@ -65,6 +58,7 @@
     "@types/react-dom": "^18",
     "react": "^18.3.0",
     "react-dom": "^18.3.0",
+    "react-router": "^7.0.0",
     "typescript": "^5.3.3"
   },
   "engines": {

package/src/components/AddToCartButton.tsx

@@ -1,47 +1,41 @@
 /**
  * <AddToCartButton> — 加入购物车按钮
  *
- * 对齐 Shopify Hydrogen：本质是包了一个 <CartForm action={LinesAdd}> + <button type="submit">。
+ * helium 0.7：对齐 Hydrogen 模式。这是 <CartForm action=LinesAdd> 的便捷包装。
  *
- *   - SSR HTML 是原生 <form>，无 JS 也能加购（form 提交 → 服务端 redirect 回 referrer）
- *   - hydrate 后 JS 拦截 submit → fetch /cart → CartProvider.applyCart → 无刷新
- *   - loading 状态由 CartForm.fetcher 暴露，通过 useFetcher() 读取
- *
- * 商家也可以直接组合 <CartForm>，不用我们这个 wrapper：
+ * 商家也可以直接用 <CartForm>（更灵活）：
  *
  *   <CartForm route="/cart" action={CartForm.ACTIONS.LinesAdd} inputs={{ lines: [...] }}>
- *     <button type="submit">加入购物车</button>
+ *     {(fetcher) => (
+ *       <button type="submit" disabled={fetcher.state !== 'idle'}>
+ *         {fetcher.state === 'idle' ? '加入购物车' : '加入中...'}
+ *       </button>
+ *     )}
  *   </CartForm>
+ *
+ * 想要加购后自定义行为（弹抽屉、跳页等）：商家组件用 useFetcher / useNavigation
+ * 监听全局 fetcher 状态。Hydrogen demo store 用 `useAside().open()` 模式。
  */
 
 import * as React from 'react';
-import { CartForm, useFetcher, type CartLineInput } from './CartForm';
-import { useAnalytics } from './AnalyticsProvider';
+import { CartForm, type CartLineInput } from './CartForm';
 
 export interface AddToCartButtonProps {
-  /** 必传：variant 的 GID（gid://shopbb/ProductVariant/...） */
+  /** variant GID */
   variantId: string;
   /** 数量，默认 1 */
   quantity?: number;
-  /** 行级 attributes（如 gift_message） */
+  /** 行级 attributes */
   attributes?: Array<{ key: string; value: string }>;
-  /** 加购成功回调（仅 hydrated 后触发） */
-  onAdded?: () => void;
-  /** 加购失败回调 */
-  onError?: (err: Error) => void;
-  /** 加购中显示的文本 */
-  loadingText?: React.ReactNode;
-  /** 不可用时显示的文本 */
+  /** optimistic UI 用：传整个 variant 对象（含 product 等） */
+  selectedVariant?: any;
+  /** Disabled 文本 */
   unavailableText?: React.ReactNode;
-  /** disabled */
   disabled?: boolean;
-  /** 包装 form className */
   className?: string;
-  /** 按钮 className */
-  buttonClassName?: string;
-  /** 提交的 route，默认 /cart */
+  /** 提交 route，默认 /cart */
   route?: string;
-  /** 按钮内容 */
+  /** 按钮 children */
   children?: React.ReactNode;
 }
 
@@ -50,90 +44,38 @@ export function AddToCartButton(props: AddToCartButtonProps) {
     variantId,
     quantity = 1,
     attributes,
-    onAdded,
-    onError,
-    loadingText = '加入中...',
+    selectedVariant,
     unavailableText = '缺货',
     disabled = false,
     className,
-    buttonClassName,
     route = '/cart',
     children = '加入购物车',
   } = props;
 
   const line: CartLineInput = { merchandiseId: variantId, quantity };
   if (attributes && attributes.length > 0) line.attributes = attributes;
+  if (selectedVariant) line.selectedVariant = selectedVariant;
 
   return (
     <CartForm
       route={route}
       action={CartForm.ACTIONS.LinesAdd}
       inputs={{ lines: [line] }}
-      className={className}
     >
-      <AddToCartButtonInner
-        disabled={disabled}
-        buttonClassName={buttonClassName}
-        loadingText={loadingText}
-        unavailableText={unavailableText}
-        variantId={variantId}
-        quantity={quantity}
-        onAdded={onAdded}
-        onError={onError}
-      >
-        {children}
-      </AddToCartButtonInner>
+      {(fetcher) => {
+        const submitting = fetcher.state !== 'idle';
+        return (
+          <button
+            type="submit"
+            className={className}
+            disabled={disabled || submitting}
+            data-add-to-cart
+            data-loading={submitting ? '' : undefined}
+          >
+            {submitting ? '加入中...' : disabled ? unavailableText : children}
+          </button>
+        );
+      }}
     </CartForm>
   );
 }
-
-/**
- * Inner component — 合法地 useFetcher / useEffect，监听 fetcher.state 变化。
- */
-function AddToCartButtonInner({
-  disabled, buttonClassName, loadingText, unavailableText, children,
-  variantId, quantity, onAdded, onError,
-}: {
-  disabled: boolean;
-  buttonClassName?: string;
-  loadingText: React.ReactNode;
-  unavailableText: React.ReactNode;
-  children: React.ReactNode;
-  variantId: string;
-  quantity: number;
-  onAdded?: () => void;
-  onError?: (err: Error) => void;
-}) {
-  const fetcher = useFetcher();
-  const analytics = useAnalytics();
-
-  // 监听 fetcher 完成
-  const prevState = React.useRef(fetcher.state);
-  React.useEffect(() => {
-    const wasNonIdle = prevState.current !== 'idle';
-    const isIdle = fetcher.state === 'idle';
-    if (wasNonIdle && isIdle) {
-      if (fetcher.error) {
-        onError?.(new Error(fetcher.error));
-      } else if (fetcher.data?.cart) {
-        analytics.emit('add_to_cart', { variantId, quantity });
-        onAdded?.();
-      }
-    }
-    prevState.current = fetcher.state;
-  }, [fetcher.state, fetcher.error, fetcher.data, onAdded, onError, analytics, variantId, quantity]);
-
-  const adding = fetcher.state !== 'idle';
-
-  return (
-    <button
-      type="submit"
-      className={buttonClassName}
-      disabled={disabled || adding}
-      data-add-to-cart
-      data-loading={adding ? '' : undefined}
-    >
-      {adding ? loadingText : disabled ? unavailableText : children}
-    </button>
-  );
-}

package/src/components/AddressForm.tsx

@@ -1,41 +1,68 @@
 /**
  * <AddressForm>
  *
- * 地址编辑 / 新增表单。**自带**：
- *   - 表单 state（useState）
- *   - 必填验证
- *   - 调 useAddressBook().createAddress / updateAddress
- *   - userErrors 显示
- *   - loading 态
+ * 地址编辑 / 新增表单。
  *
- * 用法（新增）：
- *   <AddressForm onSave={() => setCreating(false)} onCancel={...} />
+ * helium 0.7：删除 useAddressBook 调用，改为接 onSubmit prop（商家自己处理 mutation）。
  *
- * 用法（编辑）：
- *   <AddressForm initial={editingAddress} onSave={...} onCancel={...} />
- *
- * 表单不带样式（用 data-* 钩子或商家自己 className 控制）。
+ * 用法：
+ *   <AddressForm
+ *     initial={editingAddress}
+ *     onSubmit={async (input, asDefault) => {
+ *       // 商家调自己的 action 或 fetch
+ *       const result = await myCreateOrUpdate(input, asDefault);
+ *       return { userErrors: result.userErrors, address: result.address };
+ *     }}
+ *     onSaved={(addr) => setCreating(false)}
+ *     onCancel={() => setCreating(false)}
+ *   />
  */
 
 import * as React from 'react';
-import { useAddressBook, type Address, type AddressInput, type AddressBookUserError } from './AddressBookProvider';
+import type { Address } from './AddressList';
+
+export interface AddressInput {
+  firstName: string;
+  lastName?: string;
+  company?: string;
+  phone: string;
+  country?: string;
+  countryCode?: string;
+  province: string;
+  provinceCode?: string;
+  city: string;
+  district?: string;
+  address1: string;
+  address2?: string;
+  zip?: string;
+}
+
+export interface AddressBookUserError {
+  field?: string[];
+  code: string;
+  message: string;
+}
+
+export interface AddressFormSubmitResult {
+  address?: Address;
+  userErrors: AddressBookUserError[];
+}
 
 export interface AddressFormProps {
   /** 传 = 编辑模式；不传 = 新增模式 */
   initial?: Address;
+  /** 提交回调（商家实现 mutation）—— 必填 */
+  onSubmit?: (input: AddressInput, asDefault: boolean) => Promise<AddressFormSubmitResult>;
   /** 保存成功后触发 */
-  onSave?: (address?: Address) => void;
+  onSaved?: (address?: Address) => void;
   /** 取消按钮触发 */
   onCancel?: () => void;
-  /** 自定义提交按钮文字 */
   submitText?: string;
   cancelText?: string;
-  /** 显示"设为默认"复选框，默认 true */
+  /** 显示"设为默认"复选框 */
   showDefaultCheckbox?: boolean;
-  /** 哪些字段必填，默认 ['firstName','phone','address1','city','province'] */
   requiredFields?: Array<keyof AddressInput>;
   className?: string;
-  /** i18n 文案覆盖 */
   i18n?: Partial<AddressFormI18n>;
 }
 
@@ -73,7 +100,7 @@ const DEFAULT_I18N: AddressFormI18n = {
 
 export function AddressForm(props: AddressFormProps) {
   const {
-    initial, onSave, onCancel,
+    initial, onSubmit, onSaved, onCancel,
     submitText = '保存',
     cancelText = '取消',
     showDefaultCheckbox = true,
@@ -82,7 +109,6 @@ export function AddressForm(props: AddressFormProps) {
     i18n: i18nOverride,
   } = props;
 
-  const { createAddress, updateAddress } = useAddressBook();
   const i18n = { ...DEFAULT_I18N, ...i18nOverride };
 
   const [form, setForm] = React.useState<AddressInput>({
@@ -104,27 +130,31 @@ export function AddressForm(props: AddressFormProps) {
   const [saving, setSaving] = React.useState(false);
   const [errors, setErrors] = React.useState<AddressBookUserError[]>([]);
 
-  const update = (k: keyof AddressInput, v: string) => setForm((f) => ({ ...f, [k]: v }));
+  const update = (k: keyof AddressInput, v: string) =>
+    setForm((f) => ({ ...f, [k]: v } as any));
 
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
-    // 客户端必填校验
     const missing = requiredFields.filter((k) => !(form[k] && String(form[k]).trim()));
     if (missing.length > 0) {
       setErrors([{ field: missing as string[], code: 'MISSING_FIELD', message: '请填写完整地址' }]);
       return;
     }
+    if (!onSubmit) {
+      setErrors([{ code: 'NO_HANDLER', message: '商家未传入 onSubmit 处理函数' }]);
+      return;
+    }
     setSaving(true);
     setErrors([]);
     try {
-      const result = initial
-        ? await updateAddress(initial.id, form, asDefault)
-        : await createAddress(form, asDefault);
+      const result = await onSubmit(form, asDefault);
       if (result.userErrors.length > 0) {
         setErrors(result.userErrors);
         return;
       }
-      onSave?.(result.address);
+      onSaved?.(result.address);
+    } catch (e: any) {
+      setErrors([{ code: 'SUBMIT_ERROR', message: e?.message || '提交失败' }]);
     } finally {
       setSaving(false);
     }

package/src/components/AddressList.tsx

@@ -3,53 +3,63 @@
  *
  * 渲染当前买家的地址列表。
  *
- * 用法：
- *   <AddressList
- *     onEdit={(addr) => openEditModal(addr)}
- *     onAdd={() => openCreateModal()}
- *     emptyText="还没有保存的地址"
- *   />
+ * helium 0.7：addresses 通过 props 传入（不再用 AddressBookProvider）。
+ * 商家从 customer GraphQL 拉 addresses + defaultAddress 传给本组件。
+ * setDefault / remove 由商家通过 RR7 action 实现（onSetDefault / onRemove 回调）。
  */
 
 import * as React from 'react';
-import { useAddressBook, type Address } from './AddressBookProvider';
-import { useMounted } from './hooks/useMounted';
+
+export interface Address {
+  id: string;
+  firstName?: string | null;
+  lastName?: string | null;
+  name?: string | null;
+  company?: string | null;
+  phone?: string | null;
+  address1?: string | null;
+  address2?: string | null;
+  city?: string | null;
+  province?: string | null;
+  provinceCode?: string | null;
+  district?: string | null;
+  country?: string | null;
+  countryCode?: string | null;
+  zip?: string | null;
+  isDefault?: boolean;
+}
+
+export interface AddressListItemActions {
+  setDefault: () => Promise<void> | void;
+  remove: () => Promise<void> | void;
+  edit?: () => void;
+}
 
 export interface AddressListProps {
+  /** 地址列表（从 loader 传入） */
+  addresses?: Address[];
+  /** 设为默认地址回调 */
+  onSetDefault?: (addressId: string) => Promise<void> | void;
+  /** 删除地址回调 */
+  onRemove?: (addressId: string) => Promise<void> | void;
   /** 编辑按钮点击 */
   onEdit?: (address: Address) => void;
-  /** "新增" 按钮点击。不传 = 不显示新增按钮（商家自己渲染外面） */
+  /** 新增按钮点击 */
   onAdd?: () => void;
   /** 空状态文案 */
   emptyText?: React.ReactNode;
-  /** 渲染单个地址卡片的覆盖（高级用法） */
+  /** 渲染单个地址卡片的覆盖 */
   renderItem?: (address: Address, actions: AddressListItemActions) => React.ReactNode;
-  /** 整体容器 className */
   className?: string;
-  /** 加载中渲染 */
-  loadingFallback?: React.ReactNode;
-}
-
-export interface AddressListItemActions {
-  setDefault: () => Promise<void>;
-  remove: () => Promise<void>;
-  edit?: () => void;
 }
 
 export function AddressList(props: AddressListProps) {
   const {
-    onEdit, onAdd, emptyText = '还没有保存的地址',
-    renderItem, className, loadingFallback = null,
+    addresses = [],
+    onSetDefault, onRemove, onEdit, onAdd,
+    emptyText = '还没有保存的地址',
+    renderItem, className,
   } = props;
-  const mounted = useMounted();
-  const { addresses, status, setDefault, deleteAddress } = useAddressBook();
-
-  if (!mounted) {
-    return <div data-address-list data-ssr-placeholder className={className} />;
-  }
-  if (status === 'loading' || status === 'unauthenticated') {
-    return <>{loadingFallback}</>;
-  }
 
   if (addresses.length === 0) {
     return (
@@ -75,8 +85,8 @@ export function AddressList(props: AddressListProps) {
       <div data-items>
         {addresses.map((a) => {
           const actions: AddressListItemActions = {
-            setDefault: async () => { await setDefault(a.id); },
-            remove: async () => { await deleteAddress(a.id); },
+            setDefault: () => onSetDefault?.(a.id) as any,
+            remove: () => onRemove?.(a.id) as any,
             edit: onEdit ? () => onEdit(a) : undefined,
           };
           if (renderItem) return <React.Fragment key={a.id}>{renderItem(a, actions)}</React.Fragment>;
@@ -87,7 +97,6 @@ export function AddressList(props: AddressListProps) {
   );
 }
 
-// 默认渲染
 function DefaultAddressItem({ address: a, actions }: { address: Address; actions: AddressListItemActions }) {
   return (
     <div data-address-item data-default={a.isDefault ? '' : undefined}>

package/src/components/AddressPicker.tsx

@@ -1,55 +1,52 @@
 /**
  * <AddressPicker>
  *
- * Checkout 用的地址选择器。**自带**：
- *   - 从 useAddressBook() 拿 list
- *   - radio 渲染 + 默认选 defaultAddress
- *   - 选 "新地址" 时展开新增表单
+ * Checkout 用的地址选择器。
+ *
+ * helium 0.7：addresses 通过 props 传入。
  *
- * 用法（受控）：
  *   <AddressPicker
+ *     addresses={addresses}
+ *     defaultAddress={defaultAddress}
  *     value={selectedAddressId}
  *     onChange={(id, addr) => setSelectedAddressId(id)}
- *     allowNewAddress
- *     onUseNewAddress={(addr) => setInlineAddress(addr)}
  *   />
- *
- * 用法（非受控）：
- *   <AddressPicker onSelect={(addr) => ...} />
- *   组件内部 state；选择后回调商家拿值。
  */
 
 import * as React from 'react';
-import { useAddressBook, type Address } from './AddressBookProvider';
-import { useMounted } from './hooks/useMounted';
+import type { Address } from './AddressList';
 import { AddressForm } from './AddressForm';
 
 export interface AddressPickerProps {
+  /** 地址列表（从 loader 传入） */
+  addresses?: Address[];
+  /** 默认地址（用来自动选中） */
+  defaultAddress?: Address | null;
   /** 受控：当前选中的 address ID */
   value?: string | null;
-  /** 受控：选中变化（同时拿到 address 对象） */
+  /** 受控：选中变化 */
   onChange?: (addressId: string | null, address: Address | null) => void;
-  /** 非受控：选择时回调（不需要外面 state） */
+  /** 非受控：选择时回调 */
   onSelect?: (address: Address | null) => void;
   /** 是否允许"使用新地址"选项 */
   allowNewAddress?: boolean;
-  /** 选了"新地址"后填表保存的回调（拿到新建好的 Address） */
+  /** 选了"新地址"后保存的回调 */
   onUseNewAddress?: (address: Address) => void;
-  /** 空状态：没保存地址时显示什么。默认渲染内嵌 AddressForm */
+  /** 空状态 */
   emptyFallback?: React.ReactNode;
   className?: string;
 }
 
 export function AddressPicker(props: AddressPickerProps) {
   const {
+    addresses = [],
+    defaultAddress = null,
     value, onChange, onSelect,
     allowNewAddress = true,
     onUseNewAddress,
     emptyFallback,
     className,
   } = props;
-  const mounted = useMounted();
-  const { addresses, defaultAddress, status } = useAddressBook();
 
   // 非受控 fallback
   const [internalId, setInternalId] = React.useState<string | null>(null);
@@ -71,13 +68,6 @@ export function AddressPicker(props: AddressPickerProps) {
     }
   }, [defaultAddress, addresses, selectedId, setSelectedId]);
 
-  if (!mounted) {
-    return <div data-address-picker data-ssr-placeholder className={className} />;
-  }
-  if (status === 'loading') {
-    return <div data-address-picker data-loading>加载地址中…</div>;
-  }
-
   // 0 个地址：直接展示一个新增表单
   if (addresses.length === 0) {
     if (emptyFallback) return <>{emptyFallback}</>;
@@ -85,7 +75,7 @@ export function AddressPicker(props: AddressPickerProps) {
       <div data-address-picker data-empty className={className}>
         <div data-picker-title>填写收货地址</div>
         <AddressForm
-          onSave={(addr) => {
+          onSaved={(addr) => {
             if (addr) {
               setSelectedId(addr.id, addr);
               onUseNewAddress?.(addr);
@@ -129,7 +119,7 @@ export function AddressPicker(props: AddressPickerProps) {
             />
             <div>
               <div data-name>+ 使用新地址</div>
-              <div data-line>填写一个新地址（默认保存到地址簿）</div>
+              <div data-line>填写一个新地址</div>
             </div>
           </label>
         )}
@@ -142,7 +132,7 @@ export function AddressPicker(props: AddressPickerProps) {
               const fallback = defaultAddress || addresses[0];
               if (fallback) setSelectedId(fallback.id, fallback);
             }}
-            onSave={(addr) => {
+            onSaved={(addr) => {
               if (addr) {
                 setShowNewForm(false);
                 setSelectedId(addr.id, addr);

package/src/components/AnalyticsProvider.tsx

@@ -27,7 +27,6 @@
  */
 
 import * as React from 'react';
-import { useCartOptional } from './CartProvider';
 import { useShopOptional } from './ShopProvider';
 
 export interface AnalyticsEvent {
@@ -51,14 +50,16 @@ export interface AnalyticsProviderProps {
   children: React.ReactNode;
   /** 接收所有事件的回调 */
   onEvent?: (event: AnalyticsEvent) => void;
-  /** 是否自动监听 cart 变化触发 cart_updated 事件 */
-  trackCart?: boolean;
+  /**
+   * 商家可以传入当前 cart（从 loader 拿）。
+   * 每次 cart 变化（id 或 totalQuantity 变）自动触发 cart_updated 事件。
+   */
+  cart?: any;
 }
 
 export function AnalyticsProvider(props: AnalyticsProviderProps) {
-  const { children, onEvent, trackCart = true } = props;
+  const { children, onEvent, cart } = props;
   const shop = useShopOptional();
-  const cartCtx = useCartOptional();
   const onEventRef = React.useRef(onEvent);
   React.useEffect(() => {
     onEventRef.current = onEvent;
@@ -76,17 +77,21 @@ export function AnalyticsProvider(props: AnalyticsProviderProps) {
     [shop],
   );
 
-  // cart 自动追踪
+  // cart 自动追踪：通过 useEffect 比较 cart.id + totalQuantity 变化触发事件
+  const lastCartRef = React.useRef<{ id?: string; qty?: number } | null>(null);
   React.useEffect(() => {
-    if (!trackCart || !cartCtx) return;
-    return cartCtx.subscribe((c) => {
+    if (!cart) return;
+    const cur = { id: cart.id as string | undefined, qty: cart.totalQuantity as number | undefined };
+    const prev = lastCartRef.current;
+    if (!prev || prev.id !== cur.id || prev.qty !== cur.qty) {
+      lastCartRef.current = cur;
       emit('cart_updated', {
-        cartId: c?.id,
-        totalQuantity: c?.totalQuantity,
-        totalAmount: c?.cost.totalAmount,
+        cartId: cart.id,
+        totalQuantity: cart.totalQuantity,
+        totalAmount: cart.cost?.totalAmount,
       });
-    });
-  }, [trackCart, cartCtx, emit]);
+    }
+  }, [cart, emit]);
 
   return <Ctx.Provider value={{ emit }}>{children}</Ctx.Provider>;
 }