@shopbb/helium 0.5.10 → 0.6.1

package/src/components/AddToCartButton.tsx

@@ -1,101 +1,139 @@
 /**
  * <AddToCartButton> — 加入购物车按钮
  *
- * 对齐 @shopify/hydrogen <AddToCartButton>：
- *   - 内置 loading 态、disabled、error 处理
- *   - 支持 onAdd 回调（实际加购逻辑由外部 cart hook 提供）
- *   - 触发 analytics 事件钩子
- *   - 不带样式，商家自己控制
+ * 对齐 Shopify Hydrogen：本质是包了一个 <CartForm action={LinesAdd}> + <button type="submit">。
  *
- * 用法（Phase 1，需要传 onAdd）：
- *   const { addLine } = useCart();
- *   <AddToCartButton
- *     variantId={selectedVariant.id}
- *     quantity={1}
- *     disabled={!selectedVariant.availableForSale}
- *     onAdd={(vid, qty) => addLine(vid, qty)}
- *   >
- *     加入购物车
- *   </AddToCartButton>
+ *   - SSR HTML 是原生 <form>，无 JS 也能加购（form 提交 → 服务端 redirect 回 referrer）
+ *   - hydrate 后 JS 拦截 submit → fetch /cart → CartProvider.applyCart → 无刷新
+ *   - loading 状态由 CartForm.fetcher 暴露，通过 useFetcher() 读取
  *
- * Phase 2 后：组件会自动从 <CartProvider> 拿，无需 onAdd 也能用。
+ * 商家也可以直接组合 <CartForm>，不用我们这个 wrapper：
+ *
+ *   <CartForm route="/cart" action={CartForm.ACTIONS.LinesAdd} inputs={{ lines: [...] }}>
+ *     <button type="submit">加入购物车</button>
+ *   </CartForm>
  */
 
 import * as React from 'react';
-import { useCartOptional } from './CartProvider';
+import { CartForm, useFetcher, type CartLineInput } from './CartForm';
 import { useAnalytics } from './AnalyticsProvider';
 
-export interface AddToCartButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'onError'> {
+export interface AddToCartButtonProps {
   /** 必传：variant 的 GID（gid://shopbb/ProductVariant/...） */
   variantId: string;
   /** 数量，默认 1 */
   quantity?: number;
-  /** 实际加购回调。Phase 1 必传；Phase 2 后可从 Provider 自动获取 */
-  onAdd?: (variantId: string, quantity: number) => Promise<void>;
-  /** 加购成功回调（如导航到 /cart） */
+  /** 行级 attributes（如 gift_message） */
+  attributes?: Array<{ key: string; value: string }>;
+  /** 加购成功回调（仅 hydrated 后触发） */
   onAdded?: () => void;
   /** 加购失败回调 */
   onError?: (err: Error) => void;
-  /** 加购中显示的文本，默认 "加入中..." */
+  /** 加购中显示的文本 */
   loadingText?: React.ReactNode;
-  /** 不可用时显示的文本，默认 "缺货" */
+  /** 不可用时显示的文本 */
   unavailableText?: React.ReactNode;
+  /** disabled */
+  disabled?: boolean;
+  /** 包装 form className */
+  className?: string;
+  /** 按钮 className */
+  buttonClassName?: string;
+  /** 提交的 route，默认 /cart */
+  route?: string;
+  /** 按钮内容 */
+  children?: React.ReactNode;
 }
 
 export function AddToCartButton(props: AddToCartButtonProps) {
   const {
     variantId,
     quantity = 1,
-    onAdd,
+    attributes,
     onAdded,
     onError,
     loadingText = '加入中...',
     unavailableText = '缺货',
+    disabled = false,
+    className,
+    buttonClassName,
+    route = '/cart',
     children = '加入购物车',
-    disabled: disabledProp,
-    ...rest
   } = props;
 
-  const [adding, setAdding] = React.useState(false);
-  const cart = useCartOptional();
-  const analytics = useAnalytics();
+  const line: CartLineInput = { merchandiseId: variantId, quantity };
+  if (attributes && attributes.length > 0) line.attributes = attributes;
+
+  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>
+    </CartForm>
+  );
+}
 
-  const handleClick = async (e: React.MouseEvent<HTMLButtonElement>) => {
-    e.preventDefault();
-    if (adding || disabledProp) return;
+/**
+ * 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();
 
-    setAdding(true);
-    try {
-      if (onAdd) {
-        // 商家显式传了 onAdd 优先用（Phase 1 兼容路径）
-        await onAdd(variantId, quantity);
-      } else if (cart) {
-        // 自动从 <CartProvider> 取
-        await cart.linesAdd([{ merchandiseId: variantId, quantity }]);
-      } else {
-        console.warn('[AddToCartButton] no onAdd and no <CartProvider> — button does nothing');
-        return;
+  // 监听 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?.();
       }
-      analytics.emit('add_to_cart', { variantId, quantity });
-      onAdded?.();
-    } catch (err: any) {
-      console.error('[AddToCartButton] add failed:', err);
-      onError?.(err instanceof Error ? err : new Error(String(err)));
-    } finally {
-      setAdding(false);
     }
-  };
+    prevState.current = fetcher.state;
+  }, [fetcher.state, fetcher.error, fetcher.data, onAdded, onError, analytics, variantId, quantity]);
+
+  const adding = fetcher.state !== 'idle';
 
   return (
     <button
-      type="button"
-      {...rest}
+      type="submit"
+      className={buttonClassName}
+      disabled={disabled || adding}
       data-add-to-cart
       data-loading={adding ? '' : undefined}
-      disabled={disabledProp || adding}
-      onClick={handleClick}
     >
-      {adding ? loadingText : disabledProp ? unavailableText : children}
+      {adding ? loadingText : disabled ? unavailableText : children}
     </button>
   );
 }

package/src/components/BuyNowButton.tsx

@@ -0,0 +1,135 @@
+/**
+ * <BuyNowButton> — 对齐 Hydrogen React
+ *
+ * "立即购买" — 创建/添加 line + 跳 checkout，一步到位。
+ *
+ * 实现：
+ *   1. 内部包 <CartForm action="LinesAdd" inputs={{lines, navigateOnSuccess: '/checkout'}}>
+ *   2. submit 成功后 client 自动 navigate 到 checkoutUrl（或 fallback /checkout）
+ *   3. 无 JS 时：浏览器走 form POST，服务端 303 跳 /checkout
+ *
+ * 用法：
+ *   <BuyNowButton variantId="gid://..." quantity={1}>立即购买</BuyNowButton>
+ */
+
+import * as React from 'react';
+import { CartForm, useFetcher, type CartLineInput } from './CartForm';
+import { useAnalytics } from './AnalyticsProvider';
+
+export interface BuyNowButtonProps {
+  /** 必传 variant GID */
+  variantId: string;
+  /** 数量，默认 1 */
+  quantity?: number;
+  /** 行级 attributes */
+  attributes?: Array<{ key: string; value: string }>;
+  /** 加购后跳转的 URL（client 端），默认走 cart.checkoutUrl，回退 /checkout */
+  redirectTo?: string;
+  /** 失败回调 */
+  onError?: (err: Error) => void;
+  /** Loading 文案 */
+  loadingText?: React.ReactNode;
+  /** Disabled 文案 */
+  unavailableText?: React.ReactNode;
+  /** disabled */
+  disabled?: boolean;
+  /** Form className */
+  className?: string;
+  /** 按钮 className */
+  buttonClassName?: string;
+  /** 按钮 content */
+  children?: React.ReactNode;
+  /** 提交 route，默认 /cart */
+  route?: string;
+}
+
+export function BuyNowButton(props: BuyNowButtonProps) {
+  const {
+    variantId,
+    quantity = 1,
+    attributes,
+    redirectTo,
+    onError,
+    loadingText = '处理中...',
+    unavailableText = '暂不可购',
+    disabled = false,
+    className,
+    buttonClassName,
+    children = '立即购买',
+    route = '/cart',
+  } = props;
+
+  const line: CartLineInput = { merchandiseId: variantId, quantity };
+  if (attributes && attributes.length > 0) line.attributes = attributes;
+
+  return (
+    <CartForm
+      route={route}
+      action={CartForm.ACTIONS.LinesAdd}
+      inputs={{ lines: [line] }}
+      className={className}
+    >
+      <BuyNowButtonInner
+        disabled={disabled}
+        buttonClassName={buttonClassName}
+        loadingText={loadingText}
+        unavailableText={unavailableText}
+        variantId={variantId}
+        quantity={quantity}
+        redirectTo={redirectTo}
+        onError={onError}
+      >
+        {children}
+      </BuyNowButtonInner>
+    </CartForm>
+  );
+}
+
+function BuyNowButtonInner({
+  disabled, buttonClassName, loadingText, unavailableText, children,
+  variantId, quantity, redirectTo, onError,
+}: {
+  disabled: boolean;
+  buttonClassName?: string;
+  loadingText: React.ReactNode;
+  unavailableText: React.ReactNode;
+  children: React.ReactNode;
+  variantId: string;
+  quantity: number;
+  redirectTo?: string;
+  onError?: (err: Error) => void;
+}) {
+  const fetcher = useFetcher();
+  const analytics = useAnalytics();
+  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('buy_now', { variantId, quantity });
+        const target = redirectTo || (fetcher.data.cart as any).checkoutUrl || '/checkout';
+        if (typeof window !== 'undefined') {
+          window.location.href = target;
+        }
+      }
+    }
+    prevState.current = fetcher.state;
+  }, [fetcher.state, fetcher.error, fetcher.data, redirectTo, onError, analytics, variantId, quantity]);
+
+  const pending = fetcher.state !== 'idle';
+  return (
+    <button
+      type="submit"
+      className={buttonClassName}
+      disabled={disabled || pending}
+      data-buy-now
+      data-loading={pending ? '' : undefined}
+    >
+      {pending ? loadingText : disabled ? unavailableText : children}
+    </button>
+  );
+}

package/src/components/CartCheckoutButton.tsx

@@ -0,0 +1,97 @@
+/**
+ * <CartCheckoutButton> — 对齐 Hydrogen React
+ *
+ * 渲染一个跳到 cart.checkoutUrl 的按钮。最常见的"去结算"入口。
+ *
+ * 行为：
+ *   - 取 cart.checkoutUrl，无 cart / 空 cart 时按钮 disabled
+ *   - 默认 <a> 元素（无 JS 也能用），可改成 <button> + onClick
+ *   - 渲染纯样式，行为非业务逻辑
+ *
+ * 用法：
+ *   <CartCheckoutButton>去结算</CartCheckoutButton>
+ *
+ *   // 自定义渲染
+ *   <CartCheckoutButton>
+ *     {(href, disabled) => (
+ *       <a href={href} className="my-cta" aria-disabled={disabled}>
+ *         结算 {cart.totalQuantity} 件
+ *       </a>
+ *     )}
+ *   </CartCheckoutButton>
+ */
+
+import * as React from 'react';
+import { useCart } from './CartProvider';
+
+export interface CartCheckoutButtonProps {
+  /** className */
+  className?: string;
+  /** 强制 disabled（即使 cart 有 checkoutUrl） */
+  disabled?: boolean;
+  /** 按钮内容；不传默认 "去结算" */
+  children?: React.ReactNode | ((href: string, disabled: boolean) => React.ReactNode);
+  /** 自定义渲染元素，默认 a */
+  as?: 'a' | 'button';
+  /** 点击回调（事件触发） */
+  onClick?: React.MouseEventHandler;
+  /** 透传其它 props 到根元素 */
+  [key: string]: any;
+}
+
+export function CartCheckoutButton(props: CartCheckoutButtonProps) {
+  const { className, disabled: disabledProp, children, as = 'a', onClick, ...rest } = props;
+  const { cart } = useCart();
+
+  const href = (cart as any)?.checkoutUrl as string | undefined;
+  const noCart = !cart || cart.totalQuantity === 0 || !href;
+  const disabled = !!disabledProp || noCart;
+
+  if (typeof children === 'function') {
+    return <>{children(href || '#', disabled)}</>;
+  }
+
+  const label = children ?? '去结算';
+
+  if (as === 'button') {
+    return (
+      <button
+        type="button"
+        className={className}
+        disabled={disabled}
+        data-cart-checkout-button
+        onClick={(e) => {
+          if (disabled) return;
+          onClick?.(e);
+          if (!e.defaultPrevented && href) {
+            window.location.href = href;
+          }
+        }}
+        {...rest}
+      >
+        {label}
+      </button>
+    );
+  }
+
+  // <a> 形式：无 JS 也能跳
+  return (
+    <a
+      href={disabled ? undefined : href}
+      className={className}
+      aria-disabled={disabled || undefined}
+      data-cart-checkout-button
+      data-disabled={disabled ? '' : undefined}
+      onClick={(e) => {
+        if (disabled) {
+          e.preventDefault();
+          return;
+        }
+        onClick?.(e);
+      }}
+      {...rest}
+    >
+      {label}
+    </a>
+  );
+}

package/src/components/CartCost.tsx

@@ -0,0 +1,65 @@
+/**
+ * <CartCost> — 对齐 Hydrogen React
+ *
+ * 从 <CartProvider> 拿 cart.cost 渲染金额。amountType 控制渲染哪个：
+ *   "total"      → cost.totalAmount (默认)
+ *   "subtotal"   → cost.subtotalAmount
+ *   "tax"        → cost.totalTaxAmount
+ *   "duty"       → cost.totalDutyAmount
+ *   "discount"   → cost.totalDiscountAmount（shopbb-extension）
+ *
+ * 内部用 <Money> 渲染，自动按 currencyCode 加货币符号。
+ *
+ * 用法：
+ *   <CartCost amountType="subtotal" />      ¥300.00
+ *   <CartCost amountType="discount" as="strong" />  ¥30.00
+ *   <CartCost amountType="total" withoutTrailingZeros />
+ *
+ * 自定义渲染：
+ *   <CartCost amountType="total">
+ *     {(money) => <strong>{money.amount} {money.currencyCode}</strong>}
+ *   </CartCost>
+ */
+
+import * as React from 'react';
+import { useCart } from './CartProvider';
+import { Money, type MoneyProps } from './Money';
+
+export interface MoneyValue {
+  amount: string;
+  currencyCode: string;
+}
+
+export interface CartCostProps extends Omit<MoneyProps, 'data' | 'children'> {
+  /**
+   * 渲染哪一项 cost。默认 "total"。
+   * - "total"    : 含运费 / 税 / 折扣的最终金额
+   * - "subtotal" : 商品小计（折扣前 / 运费前）
+   * - "tax"      : 税
+   * - "duty"     : 关税
+   * - "discount" : 优惠金额（shopbb extension）
+   */
+  amountType?: 'total' | 'subtotal' | 'tax' | 'duty' | 'discount';
+  /** 自定义渲染：(money) => ReactNode */
+  children?: (money: MoneyValue) => React.ReactNode;
+}
+
+export function CartCost(props: CartCostProps) {
+  const { amountType = 'total', children, ...moneyProps } = props;
+  const { cart } = useCart();
+  if (!cart?.cost) return null;
+
+  const cost = cart.cost as any;
+  let money: MoneyValue | null = null;
+  switch (amountType) {
+    case 'total': money = cost.totalAmount ?? null; break;
+    case 'subtotal': money = cost.subtotalAmount ?? null; break;
+    case 'tax': money = cost.totalTaxAmount ?? cost.taxAmount ?? null; break;
+    case 'duty': money = cost.totalDutyAmount ?? cost.dutyAmount ?? null; break;
+    case 'discount': money = cost.totalDiscountAmount ?? null; break;
+  }
+  if (!money) return null;
+
+  if (children) return <>{children(money)}</>;
+  return <Money data={money} {...moneyProps} />;
+}