@shopbb/helium 0.6.3 → 0.7.0

package/src/components/hooks/useOptimisticCart.ts

@@ -1,183 +1,149 @@
 /**
- * useOptimisticCart — 对齐 Hydrogen React 同名 hook
+ * useOptimisticCart — 严格对齐 Shopify Hydrogen
  *
- * 接受 actualCart（来自 CartProvider），返回一个"叠加了所有 pending mutation"
- * 的 cart 视图。让 UI 在网络回来之前立刻反应用户操作（数量+1 / 删除等）。
+ * 源文件参考：packages/hydrogen/src/cart/optimistic/useOptimisticCart.tsx
  *
- *   const { cart: actualCart } = useCart();
- *   const cart = useOptimisticCart(actualCart);
- *   // cart 看起来已经"立刻应用了"，但 fetcher 还在跑后端
+ * 核心：用 RR7 `useFetchers()` 拿当前所有 in-flight fetcher，遍历它们的 formData
+ * 用 CartForm.getFormInput 解析出 action/inputs，合并到 actualCart 上。
  *
- * 实现：
- *   - <CartForm> submit 时把 pending action 注册到模块内 store
- *   - 完成后从 store 摘掉
- *   - useOptimisticCart 订阅 store，把 actualCart 复制一份 + 应用所有 pending
+ * 用法：
+ *   const data = useLoaderData<typeof loader>();
+ *   const cart = useOptimisticCart(data.cart);
+ *   // cart 包含 isOptimistic 字段、cart.lines 包含 in-flight 添加的 line（也带 isOptimistic）
  *
- * 简化点（vs Hydrogen 完整实现）：
- *   - 只支持 LinesAdd / LinesUpdate / LinesRemove（足够 cart 主流操作）
- *   - DiscountCodesUpdate / NoteUpdate 等不做 optimistic（这些在网络层用 applyCart 兜底）
- *   - 不持久化（页面刷新清空）
+ * 与之前 helium 0.6.x 区别：
+ *   - 删除自造 pendingStore 全局变量
+ *   - 直接用 RR7 useFetchers()
  */
 
-import * as React from 'react';
-import { useCartOptional } from '../CartProvider';
+import { useFetchers } from 'react-router';
+import { CartForm, type CartLineInput } from '../CartForm';
 
-// ============================================================
-// Pending mutation store（模块级单例）
-// ============================================================
-
-export interface PendingMutation {
-  id: string;  // unique
-  action: 'LinesAdd' | 'LinesUpdate' | 'LinesRemove';
-  inputs: any;
+interface LikeACart {
+  lines: { nodes: Array<any> };
 }
 
-// 关键：snapshot 必须是稳定引用，否则 useSyncExternalStore 每次比对都觉得变了 →
-// 无限 re-render（React #185）+ hydration mismatch（#418/#423）
-const EMPTY_SNAPSHOT: PendingMutation[] = [];
-
-const pendingStore = {
-  items: new Map<string, PendingMutation>(),
-  listeners: new Set<() => void>(),
-  cachedSnapshot: EMPTY_SNAPSHOT as PendingMutation[],
-
-  add(m: PendingMutation) {
-    this.items.set(m.id, m);
-    this.cachedSnapshot = Array.from(this.items.values());
-    this.notify();
-  },
-  remove(id: string) {
-    if (this.items.delete(id)) {
-      this.cachedSnapshot = this.items.size === 0 ? EMPTY_SNAPSHOT : Array.from(this.items.values());
-      this.notify();
+export type OptimisticCartLine<T = any> = T extends LikeACart
+  ? T['lines']['nodes'][number] & { isOptimistic?: boolean }
+  : T & { isOptimistic?: boolean };
+
+export type OptimisticCart<T = any> = T extends undefined | null
+  ? {
+      isOptimistic?: boolean;
+      lines: { nodes: Array<OptimisticCartLine> };
+      totalQuantity?: number;
     }
-  },
-  list(): PendingMutation[] {
-    // 返回稳定引用（只在 add/remove 时改变）— 满足 useSyncExternalStore 契约
-    return this.cachedSnapshot;
-  },
-  subscribe(fn: () => void): () => void {
-    this.listeners.add(fn);
-    return () => { this.listeners.delete(fn); };
-  },
-  notify() {
-    for (const fn of this.listeners) fn();
-  },
-};
+  : Omit<T, 'lines'> & {
+      isOptimistic?: boolean;
+      lines: { nodes: Array<OptimisticCartLine<T>> };
+      totalQuantity?: number;
+    };
 
 /**
- * Internal: CartForm 提交时调用，注册一个 pending mutation。返回 unregister。
+ * 给 optimistic line 一个临时 id。Hydrogen 用 `gid://shopify/CartLine/optimistic-<variantId>`。
+ * 我们 shopbb 也用类似前缀。
  */
-export function __registerPendingMutation(m: PendingMutation): () => void {
-  pendingStore.add(m);
-  return () => pendingStore.remove(m.id);
+function getOptimisticLineId(variantId: string): string {
+  return `optimistic-${variantId}`;
 }
 
-// ============================================================
-// useOptimisticCart hook
-// ============================================================
-
-export interface OptimisticCartLine {
-  id: string;
-  quantity: number;
-  isOptimistic?: boolean;
-  merchandise?: any;
-  cost?: any;
-  attributes?: any;
-  [key: string]: any;
+function isOptimisticLineId(id: string): boolean {
+  return id.startsWith('optimistic-');
 }
 
-export interface OptimisticCart<TCart = any> {
-  isOptimistic?: boolean;
-  totalQuantity?: number;
-  lines?: { nodes: OptimisticCartLine[]; edges?: any };
-  cost?: any;
-  [key: string]: any;
-}
+export function useOptimisticCart<DefaultCart = any>(
+  cart?: DefaultCart,
+): OptimisticCart<DefaultCart> {
+  const fetchers = useFetchers();
 
-export function useOptimisticCart<TCart extends OptimisticCart = OptimisticCart>(
-  actualCart: TCart | null,
-): TCart | null {
-  // 订阅 pending store 重渲染
-  const subscribe = React.useCallback((cb: () => void) => pendingStore.subscribe(cb), []);
-  const getSnapshot = React.useCallback(() => pendingStore.list(), []);
-  const pendings = React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-
-  // 如果没有 pending，CartProvider 内部的 cart 已经是最新（因为 applyCart 同步过）
-  const fallback = useCartOptional();
-  const baseCart = (actualCart ?? (fallback?.cart as any)) as TCart | null;
-
-  return React.useMemo(() => {
-    if (!baseCart) {
-      // 如果没有 actual cart 但有 pending LinesAdd → 模拟一个空 cart + 即将添加的行
-      if (pendings.length === 0) return null;
-      const optimisticLines: OptimisticCartLine[] = [];
-      for (const p of pendings) {
-        if (p.action === 'LinesAdd' && Array.isArray(p.inputs?.lines)) {
-          for (const ln of p.inputs.lines) {
-            optimisticLines.push({
-              id: `__optimistic_${p.id}_${ln.merchandiseId}`,
-              quantity: ln.quantity ?? 1,
-              merchandise: { id: ln.merchandiseId },
-              isOptimistic: true,
-            });
-          }
-        }
-      }
-      if (optimisticLines.length === 0) return null;
-      return {
-        isOptimistic: true,
-        totalQuantity: optimisticLines.reduce((s, l) => s + l.quantity, 0),
-        lines: { nodes: optimisticLines },
-      } as TCart;
-    }
+  if (!fetchers || !fetchers.length) {
+    return cart as OptimisticCart<DefaultCart>;
+  }
+
+  // 用 structuredClone 拷贝 cart（不污染 useLoaderData 的引用）
+  const optimisticCart: any = (cart as any)?.lines
+    ? (typeof structuredClone === 'function' ? structuredClone(cart) : JSON.parse(JSON.stringify(cart)))
+    : { lines: { nodes: [] } };
+
+  const cartLines: any[] = optimisticCart.lines?.nodes ?? [];
+  let isOptimistic = false;
+
+  for (const { formData } of fetchers) {
+    if (!formData) continue;
 
-    if (pendings.length === 0) return baseCart;
-
-    // 复制 lines（不深拷贝整个 cart — 只动 lines 节点列表）
-    const linesNodes = ((baseCart as any).lines?.nodes ?? []).slice() as OptimisticCartLine[];
-
-    for (const p of pendings) {
-      if (p.action === 'LinesAdd' && Array.isArray(p.inputs?.lines)) {
-        for (const ln of p.inputs.lines) {
-          // 简化：若已有相同 merchandiseId 累加，否则追加
-          const idx = linesNodes.findIndex((l) => l.merchandise?.id === ln.merchandiseId);
-          if (idx >= 0) {
-            linesNodes[idx] = {
-              ...linesNodes[idx],
-              quantity: linesNodes[idx].quantity + (ln.quantity ?? 1),
-              isOptimistic: true,
-            };
-          } else {
-            linesNodes.push({
-              id: `__optimistic_${p.id}_${ln.merchandiseId}`,
-              quantity: ln.quantity ?? 1,
-              merchandise: { id: ln.merchandiseId },
-              isOptimistic: true,
-            });
-          }
+    let cartFormData: any;
+    try {
+      cartFormData = CartForm.getFormInput(formData);
+    } catch {
+      continue;
+    }
+    if (!cartFormData?.action) continue;
+
+    if (cartFormData.action === CartForm.ACTIONS.LinesAdd) {
+      const lines: CartLineInput[] = cartFormData.inputs?.lines ?? [];
+      for (const input of lines) {
+        if (!input.selectedVariant) {
+          // 没传 selectedVariant，无法 optimistic 显示具体信息 — Hydrogen 的约束相同
+          continue;
+        }
+        const variantId = (input.selectedVariant as any)?.id;
+        const existingLine = cartLines.find(
+          (line) => line.merchandise?.id === variantId,
+        );
+        isOptimistic = true;
+        if (existingLine) {
+          existingLine.quantity = (existingLine.quantity || 1) + (input.quantity || 1);
+          existingLine.isOptimistic = true;
+        } else {
+          cartLines.unshift({
+            id: getOptimisticLineId(variantId),
+            merchandise: input.selectedVariant,
+            quantity: input.quantity || 1,
+            isOptimistic: true,
+          });
         }
-      } else if (p.action === 'LinesUpdate' && Array.isArray(p.inputs?.lines)) {
-        for (const ln of p.inputs.lines) {
-          const idx = linesNodes.findIndex((l) => l.id === ln.id);
-          if (idx >= 0) {
-            linesNodes[idx] = { ...linesNodes[idx], quantity: ln.quantity ?? linesNodes[idx].quantity, isOptimistic: true };
-          }
+      }
+    } else if (cartFormData.action === CartForm.ACTIONS.LinesRemove) {
+      const lineIds: string[] = cartFormData.inputs?.lineIds ?? [];
+      for (const lineId of lineIds) {
+        const idx = cartLines.findIndex((line) => line.id === lineId);
+        if (idx !== -1) {
+          if (isOptimisticLineId(cartLines[idx].id)) continue;
+          cartLines.splice(idx, 1);
+          isOptimistic = true;
         }
-      } else if (p.action === 'LinesRemove' && Array.isArray(p.inputs?.lineIds)) {
-        for (const id of p.inputs.lineIds) {
-          const idx = linesNodes.findIndex((l) => l.id === id);
-          if (idx >= 0) linesNodes.splice(idx, 1);
+      }
+    } else if (cartFormData.action === CartForm.ACTIONS.LinesUpdate) {
+      const lines: any[] = cartFormData.inputs?.lines ?? [];
+      for (const line of lines) {
+        const idx = cartLines.findIndex((optimisticLine) => line.id === optimisticLine.id);
+        if (idx > -1) {
+          if (isOptimisticLineId(cartLines[idx].id)) continue;
+          cartLines[idx].quantity = line.quantity as number;
+          if (cartLines[idx].quantity === 0) cartLines.splice(idx, 1);
+          isOptimistic = true;
         }
       }
     }
+  }
+
+  if (isOptimistic) optimisticCart.isOptimistic = isOptimistic;
+  optimisticCart.totalQuantity = cartLines.reduce(
+    (sum, line) => sum + (line.quantity || 0),
+    0,
+  );
+  optimisticCart.lines = { ...optimisticCart.lines, nodes: cartLines };
+
+  return optimisticCart as OptimisticCart<DefaultCart>;
+}
 
-    const totalQuantity = linesNodes.reduce((s, l) => s + l.quantity, 0);
-    return {
-      ...(baseCart as any),
-      isOptimistic: true,
-      totalQuantity,
-      lines: { ...(baseCart as any).lines, nodes: linesNodes },
-    } as TCart;
-  }, [baseCart, pendings]);
+// 旧 API 兼容（pendingStore 已废弃）
+export function __registerPendingMutation(): () => void {
+  return () => {};
+}
+
+export interface PendingMutation {
+  id: string;
+  action: 'LinesAdd' | 'LinesUpdate' | 'LinesRemove';
+  inputs: any;
 }

package/src/components/index.ts

@@ -1,42 +1,18 @@
 /**
  * @shopbb/helium/components — 商家用 React 组件
  *
- * 用法：
- *   import {
- *     ShopProvider, CartProvider, AnalyticsProvider,
- *     useShop, useCart, useAnalytics,
- *     Money, Image, ProductPrice,
- *     AddToCartButton, CartLineQuantityAdjustButton,
- *     VariantSelector, ProductOptionsProvider, useProductOptions,
- *     Analytics,
- *   } from '@shopbb/helium/components';
- *
- * 设计原则：
- *   - 无样式：组件只管行为 + 语义化 DOM，样式商家自己写
- *   - data-* 钩子：方便选择器
- *   - 对齐 Shopify Hydrogen 同名组件的 API，迁移成本低
- *   - Provider 链：<ShopProvider> > <CartProvider> > <AnalyticsProvider> > App
- *     组件优先从 Provider 拿；Provider 缺省时回退到 props 或 noop
+ * 0.7 起严格对齐 Shopify Hydrogen 设计原则：
+ *   - 数据流：服务端 loader → useLoaderData → 组件 props（不通过 Provider）
+ *   - mutation：<CartForm> + RR7 useFetcher（自动 revalidate loader）
+ *   - 删除 CartProvider / DiscountProvider / AddressBookProvider
  */
 
-// Providers + hooks
+// Providers + hooks（保留：仅 Shop / ProductOptions / CartLine / Analytics，对齐 Hydrogen）
 export { ShopProvider, useShop, useShopOptional } from './ShopProvider';
 export type { ShopContextValue, ShopProviderProps } from './ShopProvider';
-// Hydrogen-compatible alias: <ShopifyProvider> 在我们叫 <ShopProvider>，提供别名让 Hydrogen 代码无痛迁移
 export { ShopProvider as ShopifyProvider } from './ShopProvider';
 export type { ShopProviderProps as ShopifyProviderProps } from './ShopProvider';
 
-export { CartProvider, useCart, useCartOptional } from './CartProvider';
-export type {
-  Cart,
-  CartLine,
-  CartLineMerchandise,
-  CartStatus,
-  CartUserError,
-  CartContextValue,
-  CartProviderProps,
-} from './CartProvider';
-
 export {
   ProductOptionsProvider,
   useProductOptions,
@@ -50,6 +26,10 @@ export type {
 export { AnalyticsProvider, useAnalytics, Analytics } from './AnalyticsProvider';
 export type { AnalyticsEvent, AnalyticsContextValue, AnalyticsProviderProps } from './AnalyticsProvider';
 
+// CartLine context（Hydrogen 标准：cart line 子组件用 useCartLine 拿当前 line）
+export { CartLineProvider, useCartLine, useCartLineOptional } from './CartLineProvider';
+export type { CartLineProviderProps, CartLineLike } from './CartLineProvider';
+
 // 展示型组件
 export { Money } from './Money';
 export type { MoneyProps, MoneyData, MoneyMeasurement } from './Money';
@@ -60,12 +40,6 @@ export type { ImageProps, ImageData } from './Image';
 export { ProductPrice } from './ProductPrice';
 export type { ProductPriceProps } from './ProductPrice';
 
-export { AddToCartButton } from './AddToCartButton';
-export type { AddToCartButtonProps } from './AddToCartButton';
-
-export { CartLineQuantityAdjustButton } from './CartLineQuantityAdjustButton';
-export type { CartLineQuantityAdjustButtonProps } from './CartLineQuantityAdjustButton';
-
 export { VariantSelector } from './VariantSelector';
 export type {
   VariantSelectorProps,
@@ -73,51 +47,45 @@ export type {
   VariantOption,
 } from './VariantSelector';
 
-// 地址簿（W4a）
-export {
-  AddressBookProvider,
-  useAddressBook,
-  useAddressBookOptional,
-} from './AddressBookProvider';
+export { CartLineQuantity } from './CartLineQuantity';
+export type { CartLineQuantityProps } from './CartLineQuantity';
+
+export { CartCost } from './CartCost';
+export type { CartCostProps, MoneyValue } from './CartCost';
+
+export { CartCheckoutButton } from './CartCheckoutButton';
+export type { CartCheckoutButtonProps } from './CartCheckoutButton';
+
+// CartForm + useFetcher 透传（Hydrogen 标准）
+export { CartForm, CART_FORM_ACTIONS, useFetcher } from './CartForm';
 export type {
-  Address,
-  AddressInput,
-  AddressBookStatus,
-  AddressBookUserError,
-  AddressBookContextValue,
-  AddressBookProviderProps,
-} from './AddressBookProvider';
+  CartFormProps, CartFormInput, CartFormFetcher, CartFormAction,
+  CartLineInput, CartLineUpdateInput, FetcherWithComponents,
+} from './CartForm';
 
-export { AddressList } from './AddressList';
-export type { AddressListProps, AddressListItemActions } from './AddressList';
+// 按钮组件（内部用 CartForm）
+export { AddToCartButton } from './AddToCartButton';
+export type { AddToCartButtonProps } from './AddToCartButton';
+export { BuyNowButton } from './BuyNowButton';
+export type { BuyNowButtonProps } from './BuyNowButton';
 
-export { AddressForm } from './AddressForm';
-export type { AddressFormProps, AddressFormI18n } from './AddressForm';
+// useOptimisticCart — 用 RR7 useFetchers() 实现（对齐 Hydrogen）
+export { useOptimisticCart } from './hooks/useOptimisticCart';
+export type { OptimisticCart, OptimisticCartLine, PendingMutation } from './hooks/useOptimisticCart';
 
+// useMoney hook
+export { useMoney } from './hooks/useMoney';
+export type { MoneyV2, MoneyParts } from './hooks/useMoney';
+
+// 地址簿（接 props，不再用 Provider）
+export { AddressList } from './AddressList';
+export type { AddressListProps, AddressListItemActions, Address } from './AddressList';
+export { AddressForm } from './AddressForm';
+export type { AddressFormProps, AddressFormI18n, AddressInput, AddressBookUserError, AddressFormSubmitResult } 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';
-
+// 优惠券（接 props，不再用 Provider）
 export {
   AppliedDiscountList,
   ClaimableDiscountList,
@@ -129,36 +97,20 @@ export type {
   ClaimableDiscountListProps,
   DiscountClaimButtonProps,
   MyDiscountListProps,
+  Discount,
+  DiscountClaim,
+  DiscountValueType,
+  DiscountValuePercentage,
+  DiscountValueAmount,
+  DiscountValueFreeShipping,
+  DiscountAllocation,
 } from './DiscountComponents';
 
 export { DiscountSelector } from './DiscountSelector';
-export type { DiscountSelectorProps } from './DiscountSelector';
-
-// SSR / hydrate 辅助 hook
-export { useMounted } from './hooks/useMounted';
-export { useOptimisticCart } from './hooks/useOptimisticCart';
-export type { OptimisticCart, OptimisticCartLine, PendingMutation } from './hooks/useOptimisticCart';
-export { useMoney } from './hooks/useMoney';
-export type { MoneyV2, MoneyParts } from './hooks/useMoney';
-
-// CartForm — Hydrogen-compatible form-based cart mutation API
-export { CartForm, CART_FORM_ACTIONS, useFetcher } from './CartForm';
 export type {
-  CartFormProps, CartFormInput, CartFormFetcher, CartFormAction,
-  CartLineInput, CartLineUpdateInput,
-} from './CartForm';
-
-// Cart line context + 子组件
-export { CartLineProvider, useCartLine, useCartLineOptional } from './CartLineProvider';
-export type { CartLineProviderProps, CartLineLike } from './CartLineProvider';
-export { CartLineQuantity } from './CartLineQuantity';
-export type { CartLineQuantityProps } from './CartLineQuantity';
-export { CartCost } from './CartCost';
-export type { CartCostProps, MoneyValue } from './CartCost';
-export { CartCheckoutButton } from './CartCheckoutButton';
-export type { CartCheckoutButtonProps } from './CartCheckoutButton';
-export { BuyNowButton } from './BuyNowButton';
-export type { BuyNowButtonProps } from './BuyNowButton';
+  DiscountSelectorProps,
+  AppliedDiscountClaim,
+} from './DiscountSelector';
 
 // Rich text
 export { RichText } from './RichText';

package/src/createCartHandler.ts

@@ -56,10 +56,19 @@ export const DEFAULT_CART_FRAGMENT = /* GraphQL */ `
 `;
 
 export function createCartHandler(options: CartHandlerOptions): CartHandler {
-  const { storefront, getCartId, setCartId: rawSetId, responseHeaders } = options;
+  const { storefront, getCartId: rawGetCartId, setCartId: rawSetId, responseHeaders } = options;
+
+  // Stateful cart id: 在 createCart 后即时缓存，让 get() 拿到。
+  // 不然 RR7 action 后 loader revalidate 时 request.headers 没新 cookie，会丢 cart。
+  let currentCartId: string | null = rawGetCartId();
+
+  function getCartId(): string | null {
+    return currentCartId || rawGetCartId();
+  }
 
   // Set the cart ID (delegate to options.setCartId, which writes Set-Cookie)
   function setCartId(cartId: string): void {
+    currentCartId = cartId;
     rawSetId(cartId, responseHeaders);
   }
 

package/src/index.ts

@@ -18,8 +18,6 @@ export { createStorefrontClient } from './createStorefrontClient';
 export { createCartHandler, DEFAULT_CART_FRAGMENT } from './createCartHandler';
 export { cartGetIdDefault, cartSetIdDefault } from './cart-id';
 export type { CartSetIdOptions } from './cart-id';
-export { handleCartFormAction } from './handleCartFormAction';
-export type { HandleCartFormActionOptions } from './handleCartFormAction';
 export { CacheNone, CacheShort, CacheLong, CacheCustom } from './cache';
 
 // 服务端工具