@shopbb/helium 0.5.10 → 0.6.0

package/src/components/CartForm.tsx

@@ -0,0 +1,311 @@
+/**
+ * <CartForm> — 对齐 Shopify Hydrogen 的 CartForm 组件
+ *
+ * Hydrogen 文档：https://shopify.dev/docs/api/hydrogen/latest/components/cartform
+ *
+ * 用法：
+ *
+ *   import { CartForm } from '@shopby/helium';
+ *
+ *   // 加入购物车
+ *   <CartForm
+ *     action={CartForm.ACTIONS.LinesAdd}
+ *     inputs={{ lines: [{ merchandiseId, quantity: 1 }] }}
+ *     route="/cart"
+ *   >
+ *     <button type="submit">加入购物车</button>
+ *   </CartForm>
+ *
+ *   // 自定义按钮渲染
+ *   <CartForm action={CartForm.ACTIONS.LinesAdd} inputs={{ lines }}>
+ *     {(fetcher) => (
+ *       <button disabled={fetcher.state !== 'idle'}>
+ *         {fetcher.state === 'submitting' ? '添加中…' : '加入购物车'}
+ *       </button>
+ *     )}
+ *   </CartForm>
+ *
+ * 服务端（route action）：
+ *
+ *   import { CartForm } from '@shopbb/helium';
+ *
+ *   export async function action(request, context) {
+ *     const formData = await request.formData();
+ *     const { action, inputs } = CartForm.getFormInput(formData);
+ *     // ... switch(action) { ... }
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────────
+ *
+ * 实现说明：
+ *
+ *   - 渲染原生 <form method="POST">，无 JS 也能工作（form 默认提交 = 整页 POST）
+ *   - INPUT_NAME = "cartFormInput"（hidden input，value = JSON.stringify({action, inputs})）
+ *   - JS 加载后，由 helium 提供的 useCartFormFetcher hook（或 useFetcher 实现） 拦截 submit 实现"不跳页"
+ *   - 当前简化实现：hydrate 后 onSubmit preventDefault，自己用 fetch 调，调完后通过 CartProvider.applyCart 更新
+ */
+
+import * as React from 'react';
+import { useCartOptional } from './CartProvider';
+import { __registerPendingMutation } from './hooks/useOptimisticCart';
+
+// ============================================================
+// Action 枚举 — 对齐 Hydrogen CartForm.ACTIONS
+// ============================================================
+
+export const CART_FORM_ACTIONS = {
+  /** Update cart attributes */
+  AttributesUpdateInput: 'AttributesUpdateInput' as const,
+  /** Update buyer identity (email, customerAccessToken, country, etc.) */
+  BuyerIdentityUpdate: 'BuyerIdentityUpdate' as const,
+  /** Create a new cart */
+  Create: 'Create' as const,
+  /** Replace discount codes */
+  DiscountCodesUpdate: 'DiscountCodesUpdate' as const,
+  /** Replace gift card codes */
+  GiftCardCodesUpdate: 'GiftCardCodesUpdate' as const,
+  /** Append gift card codes */
+  GiftCardCodesAdd: 'GiftCardCodesAdd' as const,
+  /** Remove specific gift card codes */
+  GiftCardCodesRemove: 'GiftCardCodesRemove' as const,
+  /** Add cart lines */
+  LinesAdd: 'LinesAdd' as const,
+  /** Update cart lines (quantity / attributes) */
+  LinesUpdate: 'LinesUpdate' as const,
+  /** Remove cart lines */
+  LinesRemove: 'LinesRemove' as const,
+  /** Update cart note */
+  NoteUpdate: 'NoteUpdate' as const,
+  /** Update selected delivery options */
+  SelectedDeliveryOptionsUpdate: 'SelectedDeliveryOptionsUpdate' as const,
+  /** Set metafields */
+  MetafieldsSet: 'MetafieldsSet' as const,
+  /** Delete metafields */
+  MetafieldsDelete: 'MetafieldsDelete' as const,
+} as const;
+
+export type CartFormAction = (typeof CART_FORM_ACTIONS)[keyof typeof CART_FORM_ACTIONS] | `Custom${string}`;
+
+// ============================================================
+// Action input types — 与 Hydrogen 一致
+// ============================================================
+
+export type CartLineInput = { merchandiseId: string; quantity?: number; attributes?: Array<{ key: string; value: string }> };
+export type CartLineUpdateInput = { id: string; quantity?: number; merchandiseId?: string; attributes?: Array<{ key: string; value: string }> };
+
+interface OtherFormData {
+  [key: string]: unknown;
+}
+
+export type CartFormInput =
+  | { action: 'LinesAdd'; inputs: { lines: CartLineInput[] } & OtherFormData }
+  | { action: 'LinesUpdate'; inputs: { lines: CartLineUpdateInput[] } & OtherFormData }
+  | { action: 'LinesRemove'; inputs: { lineIds: string[] } & OtherFormData }
+  | { action: 'DiscountCodesUpdate'; inputs: { discountCodes: string[] } & OtherFormData }
+  | { action: 'NoteUpdate'; inputs: { note: string } & OtherFormData }
+  | { action: 'BuyerIdentityUpdate'; inputs: { buyerIdentity: Record<string, unknown> } & OtherFormData }
+  | { action: 'AttributesUpdateInput'; inputs: { attributes: Array<{ key: string; value: string }> } & OtherFormData }
+  | { action: 'Create'; inputs: { input: Record<string, unknown> } & OtherFormData }
+  | { action: `Custom${string}`; inputs: Record<string, unknown> };
+
+// ============================================================
+// <CartForm> 组件
+// ============================================================
+
+/** 服务端 / 客户端共享的 hidden field name — 对齐 Hydrogen */
+const INPUT_NAME = 'cartFormInput';
+
+/**
+ * Fetcher 状态对象 — 模仿 Remix useFetcher
+ *
+ * 关键属性：
+ *   - state: 'idle' | 'submitting' | 'loading'
+ *   - data: 服务端 action 返回的 JSON（成功时）
+ *   - error: 错误信息
+ */
+export interface CartFormFetcher {
+  state: 'idle' | 'submitting' | 'loading';
+  data: any;
+  error: string | null;
+  /** 取最近一次提交的 form data（optimistic UI 用） */
+  formData: FormData | null;
+}
+
+/**
+ * CartFormFetcher Context — 让 CartForm 内部任何位置都能用 useFetcher() 拿状态
+ *
+ * Hydrogen 是用 Remix global fetcher，我们用一个本地 Context。children 既可以是
+ * render prop（推荐），也可以是普通节点 + useFetcher() 调用。
+ */
+const FetcherContext = React.createContext<CartFormFetcher | null>(null);
+
+/**
+ * 在 <CartForm> 内部任何深度的组件里拿 fetcher 状态。
+ *
+ *   <CartForm action="LinesAdd" inputs={{lines}}>
+ *     <MyButton />
+ *   </CartForm>
+ *
+ *   function MyButton() {
+ *     const fetcher = useFetcher();
+ *     return <button disabled={fetcher.state !== 'idle'}>添加</button>;
+ *   }
+ */
+export function useFetcher(): CartFormFetcher {
+  const ctx = React.useContext(FetcherContext);
+  if (!ctx) {
+    throw new Error('useFetcher must be used inside a <CartForm>');
+  }
+  return ctx;
+}
+
+export interface CartFormCommonProps {
+  /** children 可以是普通节点，也可以是 (fetcher) => ReactNode */
+  children: React.ReactNode | ((fetcher: CartFormFetcher) => React.ReactNode);
+  /** 提交的 route。默认 "/cart" */
+  route?: string;
+  /** Optional key — 同一 key 的 fetcher state 共享。当前简化版未使用 */
+  fetcherKey?: string;
+  /** 表单 className（不影响行为） */
+  className?: string;
+}
+
+// Discriminated union — action + inputs 强制对齐
+export type CartFormProps = CartFormInput & CartFormCommonProps;
+
+interface CartFormImpl {
+  (props: CartFormProps): React.ReactElement;
+  ACTIONS: typeof CART_FORM_ACTIONS;
+  INPUT_NAME: typeof INPUT_NAME;
+  /**
+   * 服务端 helper：从 request.formData() 解析出 { action, inputs }
+   *
+   *   const formData = await request.formData();
+   *   const { action, inputs } = CartForm.getFormInput(formData);
+   */
+  getFormInput: (formData: FormData) => CartFormInput;
+}
+
+const CartFormBase = (props: CartFormProps): React.ReactElement => {
+  const { children, route = '/cart', className, action, inputs, ...rest } = props as any;
+  const cartCtx = useCartOptional();
+
+  // 序列化 { action, inputs } 一并放进 hidden input
+  // 服务端用 CartForm.getFormInput(formData) 反序列化
+  const payload = React.useMemo(() => JSON.stringify({ action, inputs }), [action, inputs]);
+
+  const [fetcher, setFetcher] = React.useState<CartFormFetcher>({
+    state: 'idle',
+    data: null,
+    error: null,
+    formData: null,
+  });
+
+  // hydrate 后拦截 submit；SSR 时 onSubmit 不存在 → form 原生 POST
+  const handleSubmit = React.useCallback(
+    async (e: React.FormEvent<HTMLFormElement>) => {
+      e.preventDefault();
+      const form = e.currentTarget;
+      const formData = new FormData(form);
+      setFetcher({ state: 'submitting', data: null, error: null, formData });
+
+      // 注册到 pending store — useOptimisticCart 会看到这个 mutation 立刻应用
+      // 只对 cart line 类型的 action 做（DiscountCodesUpdate / Custom* 等不做 optimistic）
+      let unregisterPending: (() => void) | null = null;
+      if (action === 'LinesAdd' || action === 'LinesUpdate' || action === 'LinesRemove') {
+        const pendingId = `${action}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        unregisterPending = __registerPendingMutation({ id: pendingId, action: action as any, inputs });
+      }
+
+      try {
+        // 显式标记 X-Helium-Fetch — 让服务端知道这是 JS fetch 不是原生 form POST
+        // 服务端 handleCartFormAction 看到此 header 会返回 JSON 而不是 303 redirect
+        const res = await fetch(route, {
+          method: 'POST',
+          body: formData,
+          credentials: 'include',
+          headers: { 'Accept': 'application/json', 'X-Helium-Fetch': '1' },
+        });
+        const data: any = await res.json().catch(() => null);
+        if (!res.ok || data?.error || data?.userErrors?.length) {
+          throw new Error(data?.error || data?.userErrors?.[0]?.message || `HTTP ${res.status}`);
+        }
+        // 服务端约定：成功时返回 { cart: Cart }
+        // 这里直接 applyCart 到 CartProvider，避免 refetch
+        if (data?.cart && cartCtx?.applyCart) {
+          cartCtx.applyCart(data.cart);
+        }
+        setFetcher({ state: 'idle', data, error: null, formData: null });
+      } catch (err: any) {
+        setFetcher({ state: 'idle', data: null, error: err.message || String(err), formData: null });
+      } finally {
+        unregisterPending?.();
+      }
+    },
+    [route, cartCtx, action, inputs],
+  );
+
+  const renderedChildren = typeof children === 'function' ? (children as (f: CartFormFetcher) => React.ReactNode)(fetcher) : children;
+
+  return (
+    <FetcherContext.Provider value={fetcher}>
+      <form
+        method="POST"
+        action={route}
+        onSubmit={handleSubmit}
+        className={className}
+        data-cart-form
+        data-cart-action={action}
+      >
+        <input type="hidden" name={INPUT_NAME} value={payload} />
+        {renderedChildren}
+      </form>
+    </FetcherContext.Provider>
+  );
+};
+
+/**
+ * 服务端 helper：从 request.formData() 还原出 { action, inputs }
+ *
+ * 与 Hydrogen 完全一致的 API：
+ *
+ *   const formData = await request.formData();
+ *   const { action, inputs } = CartForm.getFormInput(formData);
+ */
+function getFormInput(formData: FormData): CartFormInput {
+  const raw = formData.get(INPUT_NAME);
+  if (typeof raw !== 'string') {
+    throw new Error(`CartForm.getFormInput: missing field "${INPUT_NAME}" in form data`);
+  }
+  let parsed: any;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`CartForm.getFormInput: field "${INPUT_NAME}" is not valid JSON`);
+  }
+  if (!parsed || typeof parsed.action !== 'string') {
+    throw new Error('CartForm.getFormInput: missing "action" in parsed payload');
+  }
+
+  // 合并 form 里的其它字段进 inputs（对齐 Hydrogen 的 OtherFormData 设计）
+  // <CartForm action=NoteUpdate><input name="note" /></CartForm> 这种场景
+  // FormData 里同时有 cartFormInput 和 note 两个字段，inputs.note 来自 FormData 而不是 JSON。
+  const otherInputs: Record<string, unknown> = {};
+  for (const [key, value] of formData.entries()) {
+    if (key === INPUT_NAME) continue;
+    otherInputs[key] = value;
+  }
+
+  return {
+    action: parsed.action,
+    inputs: { ...otherInputs, ...(parsed.inputs || {}) },
+  } as CartFormInput;
+}
+
+// 把 ACTIONS / INPUT_NAME / getFormInput 挂到 CartForm 对象上 — 对齐 Hydrogen
+const CartForm = CartFormBase as CartFormImpl;
+CartForm.ACTIONS = CART_FORM_ACTIONS;
+CartForm.INPUT_NAME = INPUT_NAME;
+CartForm.getFormInput = getFormInput;
+
+export { CartForm };

package/src/components/CartLineProvider.tsx

@@ -0,0 +1,77 @@
+/**
+ * <CartLineProvider> + useCartLine() — 对齐 Hydrogen React
+ *
+ * 在 cart 渲染时，把单行 cart line 通过 Context 提供给子组件。子组件如
+ * <CartLineQuantity>、<CartLineQuantityAdjustButton>、商品图缩略图等都能直接
+ * useCartLine() 拿到 line 数据，无需 prop drilling。
+ *
+ * 用法：
+ *
+ *   {cart.lines.nodes.map((line) => (
+ *     <CartLineProvider key={line.id} line={line}>
+ *       <CartLineImage />
+ *       <CartLineTitle />
+ *       <CartLineQuantity />
+ *       <CartLineQuantityAdjustButton />
+ *     </CartLineProvider>
+ *   ))}
+ *
+ *   function CartLineImage() {
+ *     const line = useCartLine();
+ *     return <Image data={line.merchandise.image} />;
+ *   }
+ */
+
+import * as React from 'react';
+
+/**
+ * Cart line 的核心字段。任何符合此 shape 的对象都能传入。
+ * 实际可以包含更多字段（merchandise / attributes / 等），由 oxygen Storefront
+ * GraphQL schema 决定。
+ */
+export interface CartLineLike {
+  id: string;
+  quantity: number;
+  merchandise?: {
+    id?: string;
+    title?: string;
+    image?: { url: string; altText?: string | null } | null;
+    price?: { amount: string; currencyCode: string };
+    product?: { title?: string; handle?: string } | null;
+  };
+  cost?: {
+    totalAmount: { amount: string; currencyCode: string };
+    amountPerQuantity?: { amount: string; currencyCode: string };
+  };
+  attributes?: Array<{ key: string; value: string }>;
+  [key: string]: any;
+}
+
+const CartLineContext = React.createContext<CartLineLike | null>(null);
+
+export interface CartLineProviderProps {
+  line: CartLineLike;
+  children: React.ReactNode;
+}
+
+export function CartLineProvider({ line, children }: CartLineProviderProps) {
+  return <CartLineContext.Provider value={line}>{children}</CartLineContext.Provider>;
+}
+
+/**
+ * 拿当前 cart line。Provider 外抛错。
+ */
+export function useCartLine(): CartLineLike {
+  const line = React.useContext(CartLineContext);
+  if (!line) {
+    throw new Error('useCartLine must be used inside <CartLineProvider>');
+  }
+  return line;
+}
+
+/**
+ * 非 throw 版本：Provider 外返回 null。供能在 Provider 内外都工作的组件用。
+ */
+export function useCartLineOptional(): CartLineLike | null {
+  return React.useContext(CartLineContext);
+}

package/src/components/CartLineQuantity.tsx

@@ -0,0 +1,37 @@
+/**
+ * <CartLineQuantity> — 对齐 Hydrogen React
+ *
+ * 渲染当前 cart line 的数量。从 <CartLineProvider> Context 拿 line.quantity。
+ *
+ * 用法：
+ *   <CartLineProvider line={line}>
+ *     数量：<CartLineQuantity />
+ *   </CartLineProvider>
+ *
+ * 自定义渲染元素：
+ *   <CartLineQuantity as="strong" className="qty-badge" />
+ */
+
+import * as React from 'react';
+import { useCartLine } from './CartLineProvider';
+
+export interface CartLineQuantityProps {
+  /** 渲染标签，默认 span */
+  as?: keyof JSX.IntrinsicElements;
+  /** className */
+  className?: string;
+  /** 子节点 — 数字会显示在 children 之前；通常不传 */
+  children?: React.ReactNode;
+}
+
+export function CartLineQuantity(props: CartLineQuantityProps) {
+  const { as, className, children } = props;
+  const line = useCartLine();
+  const Tag: any = as || 'span';
+  return (
+    <Tag className={className} data-cart-line-quantity>
+      {line.quantity}
+      {children}
+    </Tag>
+  );
+}

package/src/components/DiscountSelector.tsx

@@ -18,9 +18,9 @@
 
 import * as React from 'react';
 import { useDiscounts, type DiscountClaim } from './DiscountProvider';
-import { useAnalytics } from './AnalyticsProvider';
 import { Money } from './Money';
 import { useMounted } from './hooks/useMounted';
+import { CartForm } from './CartForm';
 
 export interface DiscountSelectorProps {
   className?: string;
@@ -36,15 +36,11 @@ export function DiscountSelector(props: DiscountSelectorProps) {
   const {
     myDiscounts, myDiscountsStatus,
     cartAllocations, appliedClaim,
-    selectCartDiscount,
   } = useDiscounts();
-  const analytics = useAnalytics();
 
   const [open, setOpen] = React.useState(false);
-  const [pending, setPending] = React.useState(false);
 
   // SSR + client 首次 render：返回固定占位，保证 hydration 不 mismatch。
-  // mounted 后才进入真正的渲染分支。
   if (!mounted) {
     return <div data-discount-selector data-ssr-placeholder className={className} />;
   }
@@ -54,17 +50,6 @@ export function DiscountSelector(props: DiscountSelectorProps) {
   const appliedClaimId = appliedClaim?.claimId ?? null;
   const appliedTitle = appliedClaim?.title ?? appliedAlloc?.title;
   const appliedCode = appliedClaim?.code ?? appliedAlloc?.code;
-
-  const handleSelect = async (claimId: string) => {
-    setPending(true);
-    try {
-      await selectCartDiscount(claimId);
-      analytics.emit('discount_select', { claimId });
-    } finally {
-      setPending(false);
-      setOpen(false);
-    }
-  };
   // 未登录
   if (myDiscountsStatus === 'unauthenticated') {
     return unauthenticatedFallback !== undefined ? <>{unauthenticatedFallback}</> : (
@@ -108,7 +93,7 @@ export function DiscountSelector(props: DiscountSelectorProps) {
                 )}
               </div>
               <div data-actions>
-                <button type="button" onClick={() => setOpen(true)} disabled={pending}>切换</button>
+                <button type="button" onClick={() => setOpen(true)}>切换</button>
               </div>
             </div>
           )
@@ -117,7 +102,7 @@ export function DiscountSelector(props: DiscountSelectorProps) {
             <div data-info>
               <span data-label>有 {availableClaims.length} 张可用优惠券</span>
             </div>
-            <button type="button" onClick={() => setOpen(true)} disabled={pending}>选择</button>
+            <button type="button" onClick={() => setOpen(true)}>选择</button>
           </div>
         )}
       </div>
@@ -126,9 +111,7 @@ export function DiscountSelector(props: DiscountSelectorProps) {
         <DiscountPickerSheet
           claims={availableClaims}
           currentClaimId={appliedClaimId}
-          onSelect={handleSelect}
           onClose={() => setOpen(false)}
-          pending={pending}
         />
       )}
     </>
@@ -140,13 +123,11 @@ export function DiscountSelector(props: DiscountSelectorProps) {
  * Demo 实现为屏底固定面板；商家可以替换为 modal / 抽屉等。
  */
 function DiscountPickerSheet({
-  claims, currentClaimId, onSelect, onClose, pending,
+  claims, currentClaimId, onClose,
 }: {
   claims: DiscountClaim[];
   currentClaimId: string | null;
-  onSelect: (claimId: string) => void;
   onClose: () => void;
-  pending: boolean;
 }) {
   return (
     <div data-discount-picker-overlay onClick={onClose}>
@@ -157,34 +138,42 @@ function DiscountPickerSheet({
         </div>
         <div data-sheet-list>
           {claims.map((c) => {
+            // claim_id 既可能是 gid 也可能是 raw —— oxygen mutation 接受两种
             const id = c.id.replace(/^gid:\/\/shopbb\/DiscountClaim\//, '');
             const isCurrent = currentClaimId === id;
             return (
-              <button
+              // 每张券一个 <CartForm>，submit 走 /cart action → cart.selectDiscount
+              <CartForm
                 key={c.id}
-                type="button"
-                data-claim-card
-                data-current={isCurrent ? '' : undefined}
-                onClick={() => onSelect(id)}
-                disabled={pending}
+                action="CustomDiscountSelect"
+                inputs={{ claimId: id }}
               >
-                <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 }} /> 可用
+                {(fetcher) => (
+                  <button
+                    type="submit"
+                    data-claim-card
+                    data-current={isCurrent ? '' : undefined}
+                    disabled={fetcher.state !== 'idle'}
+                  >
+                    <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>
-                  )}
-                </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>
+                    {isCurrent && <span data-claim-current-tag>当前使用</span>}
+                  </button>
+                )}
+              </CartForm>
             );
           })}
         </div>

package/src/components/Image.tsx

@@ -1,3 +1,30 @@
+/**
+ * IMAGE_FRAGMENT — 对齐 Hydrogen React 同名常量
+ *
+ * 商家在 GraphQL 查询里直接用：
+ *
+ *   import { IMAGE_FRAGMENT } from '@shopbb/helium';
+ *
+ *   const Q = `
+ *     ${IMAGE_FRAGMENT}
+ *     query {
+ *       product(handle: "x") {
+ *         featuredImage { ...Image }
+ *         images(first: 5) { nodes { ...Image } }
+ *       }
+ *     }
+ *   `;
+ */
+export const IMAGE_FRAGMENT = /* GraphQL */ `
+  fragment Image on Image {
+    id
+    url
+    altText
+    width
+    height
+  }
+`;
+
 /**
  * <Image> — 响应式商品图片
  *