@shopbb/helium 0.6.4 → 0.7.0

package/src/components/CartForm.tsx

@@ -1,97 +1,67 @@
 /**
- * <CartForm> — 对齐 Shopify Hydrogen 的 CartForm 组件
+ * <CartForm> — 严格对齐 Shopify Hydrogen 的 CartForm 实现
  *
- * Hydrogen 文档：https://shopify.dev/docs/api/hydrogen/latest/components/cartform
+ * 源文件参考：packages/hydrogen/src/cart/CartForm.tsx
  *
- * 用法：
+ * 核心机制：
+ *   - 用 react-router 的 useFetcher() + <fetcher.Form>
+ *   - submit 后 RR7 自动调对应 route 的 action()，完成后自动 revalidate 所有 loader
+ *   - children 是 render prop 可以接 fetcher 对象（state / data / formData）
+ *   - fetcherKey 让相同的 mutation 互相 cancel（例如多次点 +/- 只跑最后一次）
  *
- *   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 更新
+ * 与 helium 0.6.x 之前的差异：
+ *   - 删除自己造的 FetcherContext + raw fetch 实现
+ *   - peerDep 加 react-router（这就是 Hydrogen 自己的依赖）
  */
 
 import * as React from 'react';
-import { useCartOptional } from './CartProvider';
-import { __registerPendingMutation } from './hooks/useOptimisticCart';
+import { useFetcher, type FetcherWithComponents } from 'react-router';
 
 // ============================================================
 // 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,
+  AttributesUpdateInput: 'AttributesUpdateInput',
+  BuyerIdentityUpdate: 'BuyerIdentityUpdate',
+  Create: 'Create',
+  DiscountCodesUpdate: 'DiscountCodesUpdate',
+  GiftCardCodesUpdate: 'GiftCardCodesUpdate',
+  GiftCardCodesAdd: 'GiftCardCodesAdd',
+  GiftCardCodesRemove: 'GiftCardCodesRemove',
+  LinesAdd: 'LinesAdd',
+  LinesRemove: 'LinesRemove',
+  LinesUpdate: 'LinesUpdate',
+  NoteUpdate: 'NoteUpdate',
+  SelectedDeliveryOptionsUpdate: 'SelectedDeliveryOptionsUpdate',
+  MetafieldsSet: 'MetafieldsSet',
+  MetafieldDelete: 'MetafieldDelete',
+  DeliveryAddressesAdd: 'DeliveryAddressesAdd',
+  DeliveryAddressesUpdate: 'DeliveryAddressesUpdate',
+  DeliveryAddressesRemove: 'DeliveryAddressesRemove',
+  DeliveryAddressesReplace: 'DeliveryAddressesReplace',
 } as const;
 
 export type CartFormAction = (typeof CART_FORM_ACTIONS)[keyof typeof CART_FORM_ACTIONS] | `Custom${string}`;
 
 // ============================================================
-// Action input types — 与 Hydrogen 一致
+// Input types — 与 Hydrogen 一致（简化版，省略 metafield 等）
 // ============================================================
 
-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 }> };
+export interface CartLineInput {
+  merchandiseId: string;
+  quantity?: number;
+  attributes?: Array<{ key: string; value: string }>;
+  /** 用于 optimistic UI 展示（不会发到服务端） */
+  selectedVariant?: unknown;
+}
+
+export interface CartLineUpdateInput {
+  id: string;
+  quantity?: number;
+  merchandiseId?: string;
+  attributes?: Array<{ key: string; value: string }>;
+}
 
 interface OtherFormData {
   [key: string]: unknown;
@@ -109,203 +79,89 @@ export type CartFormInput =
   | { action: `Custom${string}`; inputs: Record<string, unknown> };
 
 // ============================================================
-// <CartForm> 组件
+// 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" */
+  /** children 可以是普通 React 节点，也可以是 render prop 接收 fetcher 对象 */
+  children: React.ReactNode | ((fetcher: FetcherWithComponents<any>) => React.ReactNode);
+  /** 提交的 route。默认空字符串表示当前 route */
   route?: string;
-  /** Optional key — 同一 key 的 fetcher state 共享。当前简化版未使用 */
+  /** Fetcher key — 相同 key 的 fetcher 会互相 cancel（用于幂等操作）*/
   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;
 }
 
+/**
+ * 严格照抄 Hydrogen 实现（packages/hydrogen/src/cart/CartForm.tsx）
+ */
 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;
+  const { children, action, inputs, route, fetcherKey } = props as any;
+  const fetcher = useFetcher({ key: fetcherKey });
 
   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>
+    <fetcher.Form action={route || ''} method="post">
+      {(action || inputs) && (
+        <input
+          type="hidden"
+          name={INPUT_NAME}
+          value={JSON.stringify({ action, inputs })}
+        />
+      )}
+      {typeof children === 'function' ? children(fetcher) : children}
+    </fetcher.Form>
   );
 };
 
 /**
  * 服务端 helper：从 request.formData() 还原出 { action, inputs }
  *
- * 与 Hydrogen 完全一致的 API：
- *
- *   const formData = await request.formData();
- *   const { action, inputs } = CartForm.getFormInput(formData);
+ * 严格照抄 Hydrogen 实现：把 form 内其它 input（如 <input name="note">）合并进 inputs。
  */
 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 data
+  const data: Record<string, unknown> = {};
+  for (const pair of formData.entries()) {
+    const key = pair[0];
+    const values = formData.getAll(key);
+    data[key] = values.length > 1 ? values : pair[1];
+    // checkbox → boolean
+    if (data[key] === 'on') data[key] = true;
+    else if (data[key] === 'off') data[key] = false;
   }
 
-  // 合并 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;
-  }
+  const { cartFormInput, ...otherData } = data;
+  const parsed: any = cartFormInput ? JSON.parse(String(cartFormInput)) : {};
 
   return {
     action: parsed.action,
-    inputs: { ...otherInputs, ...(parsed.inputs || {}) },
+    inputs: {
+      ...(parsed.inputs || {}),
+      ...otherData,
+    },
   } 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 };
+
+// useFetcher 透传 — 让商家也能用同款 API（其实就是 RR7 原生）
+export { useFetcher } from 'react-router';
+export type { FetcherWithComponents } from 'react-router';
+
+// 为了 backward compat，保留旧 CartFormFetcher 别名
+export type CartFormFetcher = FetcherWithComponents<any>;