@shopbb/helium 0.2.0 → 0.3.0-alpha.2

package/src/components/AnalyticsProvider.tsx

@@ -0,0 +1,175 @@
+/**
+ * <AnalyticsProvider> + useAnalytics() + <Analytics.*> 事件组件
+ *
+ * 简单事件总线：
+ *   - 商家注册 reporters（GA / Plausible / 自家 API）
+ *   - 通过 <Analytics.PageView /> / <Analytics.ProductView /> 等组件声明式触发
+ *   - 也可以 useAnalytics().emit(name, data)
+ *
+ * 用法：
+ *   <AnalyticsProvider
+ *     onEvent={(e) => {
+ *       fetch('/api/analytics', { method: 'POST', body: JSON.stringify(e) });
+ *       window.dataLayer?.push(e);
+ *     }}
+ *   >
+ *     <App />
+ *   </AnalyticsProvider>
+ *
+ *   // 在某页：
+ *   <Analytics.PageView path="/products" title="Products" />
+ *   <Analytics.ProductView product={product} />
+ *   <Analytics.AddToCart cart={cart} addedLineId={lineId} />
+ *
+ *   // 命令式：
+ *   const { emit } = useAnalytics();
+ *   emit('search', { query: 'wireless' });
+ */
+
+import * as React from 'react';
+import { useCartOptional } from './CartProvider';
+import { useShopOptional } from './ShopProvider';
+
+export interface AnalyticsEvent {
+  /** 事件名，例如 'page_view' / 'product_view' / 'add_to_cart' */
+  name: string;
+  /** 时间戳 (ms) */
+  timestamp: number;
+  /** 当前 shop（如果在 ShopProvider 内） */
+  shop?: { storeId: string; shopName: string } | null;
+  /** 自定义 payload */
+  payload: Record<string, any>;
+}
+
+export interface AnalyticsContextValue {
+  emit: (name: string, payload?: Record<string, any>) => void;
+}
+
+const Ctx = React.createContext<AnalyticsContextValue | null>(null);
+
+export interface AnalyticsProviderProps {
+  children: React.ReactNode;
+  /** 接收所有事件的回调 */
+  onEvent?: (event: AnalyticsEvent) => void;
+  /** 是否自动监听 cart 变化触发 cart_updated 事件 */
+  trackCart?: boolean;
+}
+
+export function AnalyticsProvider(props: AnalyticsProviderProps) {
+  const { children, onEvent, trackCart = true } = props;
+  const shop = useShopOptional();
+  const cartCtx = useCartOptional();
+  const onEventRef = React.useRef(onEvent);
+  React.useEffect(() => {
+    onEventRef.current = onEvent;
+  }, [onEvent]);
+
+  const emit = React.useCallback(
+    (name: string, payload: Record<string, any> = {}) => {
+      onEventRef.current?.({
+        name,
+        timestamp: Date.now(),
+        shop: shop ? { storeId: shop.storeId, shopName: shop.shopName } : null,
+        payload,
+      });
+    },
+    [shop],
+  );
+
+  // cart 自动追踪
+  React.useEffect(() => {
+    if (!trackCart || !cartCtx) return;
+    return cartCtx.subscribe((c) => {
+      emit('cart_updated', {
+        cartId: c?.id,
+        totalQuantity: c?.totalQuantity,
+        totalAmount: c?.cost.totalAmount,
+      });
+    });
+  }, [trackCart, cartCtx, emit]);
+
+  return <Ctx.Provider value={{ emit }}>{children}</Ctx.Provider>;
+}
+
+export function useAnalytics(): AnalyticsContextValue {
+  const v = React.useContext(Ctx);
+  if (!v) {
+    // 没 Provider 时返回 noop（不 throw，便于组件可选嵌入）
+    return { emit: () => {} };
+  }
+  return v;
+}
+
+// ============================================================
+// 声明式事件组件
+// ============================================================
+
+function useEmitOnMount(name: string, payload: Record<string, any>) {
+  const { emit } = useAnalytics();
+  const payloadRef = React.useRef(payload);
+  payloadRef.current = payload;
+  React.useEffect(() => {
+    emit(name, payloadRef.current);
+    // 只 mount 时触发一次（路由切换会重新 mount）
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  return null;
+}
+
+function PageView(props: { path?: string; title?: string; [key: string]: any }) {
+  return useEmitOnMount('page_view', props);
+}
+
+function ProductView(props: { product: { id: string; handle?: string; title?: string }; [key: string]: any }) {
+  const { product, ...rest } = props;
+  return useEmitOnMount('product_view', {
+    ...rest,
+    productId: product.id,
+    productHandle: product.handle,
+    productTitle: product.title,
+  });
+}
+
+function CollectionView(props: { collection: { id: string; handle?: string }; [key: string]: any }) {
+  const { collection, ...rest } = props;
+  return useEmitOnMount('collection_view', {
+    ...rest,
+    collectionId: collection.id,
+    collectionHandle: collection.handle,
+  });
+}
+
+function SearchView(props: { query: string; results?: number }) {
+  return useEmitOnMount('search', { query: props.query, results: props.results });
+}
+
+function AddToCart(props: { variantId: string; quantity?: number; [key: string]: any }) {
+  const { variantId, quantity, ...rest } = props;
+  return useEmitOnMount('add_to_cart', {
+    ...rest,
+    variantId,
+    quantity: quantity ?? 1,
+  });
+}
+
+function CheckoutStart(props: { cart?: { id: string; totalQuantity?: number } }) {
+  return useEmitOnMount('checkout_start', {
+    cartId: props.cart?.id,
+    totalQuantity: props.cart?.totalQuantity,
+  });
+}
+
+function Purchase(props: { orderId: string; total: number; currencyCode: string; [key: string]: any }) {
+  return useEmitOnMount('purchase', props);
+}
+
+/** 命名空间导出，让用户写 <Analytics.PageView /> */
+export const Analytics = {
+  PageView,
+  ProductView,
+  CollectionView,
+  SearchView,
+  AddToCart,
+  CheckoutStart,
+  Purchase,
+};

package/src/components/CartLineQuantityAdjustButton.tsx

@@ -0,0 +1,119 @@
+/**
+ * <CartLineQuantityAdjustButton> — cart 行数量加减按钮
+ *
+ * 对齐 @shopify/hydrogen <CartLineQuantityAdjustButton>:
+ *   - +/- 按钮调用 onChange
+ *   - 防抖（300ms）避免点快导致多次请求
+ *   - min/max 校验
+ *   - 移除时弹确认（可选）
+ *
+ * 用法：
+ *   const { updateLine, removeLine } = useCart();
+ *   <CartLineQuantityAdjustButton
+ *     line={line}
+ *     onUpdate={(newQty) => updateLine(line.id, newQty)}
+ *     onRemove={() => removeLine(line.id)}
+ *   />
+ */
+
+import * as React from 'react';
+
+export interface CartLineQuantityAdjustButtonProps {
+  /** line 的当前数量 */
+  quantity: number;
+  /** 最小值，默认 1（小于此值改成 remove） */
+  min?: number;
+  /** 最大值，默认 99 */
+  max?: number;
+  /** 数量变化回调 */
+  onUpdate?: (newQuantity: number) => Promise<void> | void;
+  /** 数量降到 0 时触发 remove */
+  onRemove?: () => Promise<void> | void;
+  /** 防抖延迟（ms），默认 300 */
+  debounceMs?: number;
+  /** 自定义包装容器 className */
+  className?: string;
+  /** 减号按钮 props 透传 */
+  decreaseProps?: React.ButtonHTMLAttributes<HTMLButtonElement>;
+  /** 加号按钮 props 透传 */
+  increaseProps?: React.ButtonHTMLAttributes<HTMLButtonElement>;
+}
+
+export function CartLineQuantityAdjustButton(props: CartLineQuantityAdjustButtonProps) {
+  const {
+    quantity,
+    min = 1,
+    max = 99,
+    onUpdate,
+    onRemove,
+    debounceMs = 300,
+    className,
+    decreaseProps,
+    increaseProps,
+  } = props;
+
+  // optimistic 显示的 quantity
+  const [optimistic, setOptimistic] = React.useState(quantity);
+  React.useEffect(() => setOptimistic(quantity), [quantity]);
+
+  const [pending, setPending] = React.useState(false);
+  const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const flushUpdate = React.useCallback(
+    (target: number) => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(async () => {
+        setPending(true);
+        try {
+          if (target < min) {
+            await onRemove?.();
+          } else {
+            await onUpdate?.(target);
+          }
+        } finally {
+          setPending(false);
+        }
+      }, debounceMs);
+    },
+    [min, onRemove, onUpdate, debounceMs],
+  );
+
+  const handleAdjust = (delta: number) => {
+    const next = optimistic + delta;
+    if (next > max) return;
+    setOptimistic(next);
+    flushUpdate(next);
+  };
+
+  React.useEffect(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+  }, []);
+
+  return (
+    <div className={className} data-quantity-adjust style={{ display: 'inline-flex', alignItems: 'center' }}>
+      <button
+        type="button"
+        {...decreaseProps}
+        aria-label="减少"
+        data-quantity-decrease
+        onClick={() => handleAdjust(-1)}
+        disabled={pending && optimistic <= min}
+      >
+        {decreaseProps?.children ?? '−'}
+      </button>
+      <span data-quantity-value aria-live="polite" style={{ margin: '0 0.5em', minWidth: '1.5em', textAlign: 'center' }}>
+        {optimistic}
+      </span>
+      <button
+        type="button"
+        {...increaseProps}
+        aria-label="增加"
+        data-quantity-increase
+        onClick={() => handleAdjust(1)}
+        disabled={pending && optimistic >= max}
+      >
+        {increaseProps?.children ?? '+'}
+      </button>
+    </div>
+  );
+}

package/src/components/CartProvider.tsx

@@ -0,0 +1,378 @@
+/**
+ * <CartProvider> + useCart()
+ *
+ * 接管 cart 全生命周期：
+ *   - 自动从 cookie 读取 cart_id 并 fetch
+ *   - 不存在则懒创建
+ *   - linesAdd / linesUpdate / linesRemove 全部带 optimistic update + 失败回滚
+ *   - subscribe(callback) 给外部（如 Analytics）订阅 cart 变化
+ *
+ * 用法：
+ *   <ShopProvider {...}>
+ *     <CartProvider>
+ *       <App />
+ *     </CartProvider>
+ *   </ShopProvider>
+ *
+ *   const { cart, status, linesAdd, linesUpdate, linesRemove } = useCart();
+ *
+ * 注意：必须套在 <ShopProvider> 内（依赖它的 storefrontAccessToken + apiUrl）。
+ */
+
+import * as React from 'react';
+import { useShop } from './ShopProvider';
+
+// ============================================================
+// Types
+// ============================================================
+
+export interface CartLineMerchandise {
+  id: string;
+  title?: string;
+  image?: { url: string; altText?: string | null; width?: number | null; height?: number | null };
+  price?: { amount: string; currencyCode: string };
+  product?: { title: string; handle: string };
+}
+
+export interface CartLine {
+  id: string;
+  quantity: number;
+  merchandise: CartLineMerchandise;
+  cost: { totalAmount: { amount: string; currencyCode: string } };
+}
+
+export interface Cart {
+  id: string;
+  totalQuantity: number;
+  checkoutUrl: string;
+  lines: { nodes: CartLine[] };
+  cost: {
+    subtotalAmount: { amount: string; currencyCode: string };
+    totalAmount: { amount: string; currencyCode: string };
+  };
+}
+
+export type CartStatus = 'uninitialized' | 'loading' | 'idle' | 'updating' | 'error';
+
+export interface CartUserError {
+  field?: string[] | null;
+  message: string;
+  code?: string;
+}
+
+export interface CartContextValue {
+  cart: Cart | null;
+  status: CartStatus;
+  error: string | null;
+  /** 加 line */
+  linesAdd: (lines: Array<{ merchandiseId: string; quantity?: number }>) => Promise<void>;
+  /** 更新数量（lineId, quantity）；quantity<=0 等价 remove */
+  linesUpdate: (lines: Array<{ id: string; quantity: number }>) => Promise<void>;
+  /** 删 line */
+  linesRemove: (lineIds: string[]) => Promise<void>;
+  /** 重新从服务端拉 cart */
+  refetch: () => Promise<void>;
+  /** 订阅 cart 变化（Analytics 用） */
+  subscribe: (listener: (cart: Cart | null) => void) => () => void;
+}
+
+const CartContext = React.createContext<CartContextValue | null>(null);
+
+// ============================================================
+// GraphQL
+// ============================================================
+
+const CART_FRAGMENT = /* GraphQL */ `
+  fragment CartParts on Cart {
+    id totalQuantity checkoutUrl
+    lines(first: 100) {
+      nodes {
+        id quantity
+        merchandise {
+          ... on ProductVariant {
+            id title
+            image { url altText width height }
+            price { amount currencyCode }
+            product { title handle }
+          }
+        }
+        cost { totalAmount { amount currencyCode } }
+      }
+    }
+    cost {
+      subtotalAmount { amount currencyCode }
+      totalAmount { amount currencyCode }
+    }
+  }
+`;
+
+const Q_GET_CART = CART_FRAGMENT + `
+  query GetCart($id: ID!) { cart(id: $id) { ...CartParts } }
+`;
+const M_CART_CREATE = CART_FRAGMENT + `
+  mutation Create($input: CartInput) {
+    cartCreate(input: $input) { cart { ...CartParts } userErrors { field message code } }
+  }
+`;
+const M_LINES_ADD = CART_FRAGMENT + `
+  mutation Add($cartId: ID!, $lines: [CartLineInput!]!) {
+    cartLinesAdd(cartId: $cartId, lines: $lines) { cart { ...CartParts } userErrors { field message code } }
+  }
+`;
+const M_LINES_UPDATE = CART_FRAGMENT + `
+  mutation Update($cartId: ID!, $lines: [CartLineUpdateInput!]!) {
+    cartLinesUpdate(cartId: $cartId, lines: $lines) { cart { ...CartParts } userErrors { field message code } }
+  }
+`;
+const M_LINES_REMOVE = CART_FRAGMENT + `
+  mutation Remove($cartId: ID!, $lineIds: [ID!]!) {
+    cartLinesRemove(cartId: $cartId, lineIds: $lineIds) { cart { ...CartParts } userErrors { field message code } }
+  }
+`;
+
+// ============================================================
+// cookie cart id
+// ============================================================
+
+const COOKIE_NAME = 'cart';
+
+function readCartIdFromCookie(): string | null {
+  if (typeof document === 'undefined') return null;
+  const m = document.cookie.match(new RegExp('(?:^|; )' + COOKIE_NAME + '=([^;]+)'));
+  if (!m) return null;
+  return `gid://shopbb/Cart/${decodeURIComponent(m[1])}`;
+}
+
+function saveCartIdToCookie(cartGid: string) {
+  if (typeof document === 'undefined') return;
+  const id = cartGid.replace(/^gid:\/\/shopbb\/Cart\//, '');
+  const oneYear = 365 * 24 * 60 * 60;
+  document.cookie = `${COOKIE_NAME}=${encodeURIComponent(id)}; path=/; max-age=${oneYear}; SameSite=Lax`;
+}
+
+// ============================================================
+// Provider
+// ============================================================
+
+export interface CartProviderProps {
+  children: React.ReactNode;
+  /** 加载完成后是否自动拉 cart。默认 true */
+  fetchOnMount?: boolean;
+}
+
+export function CartProvider({ children, fetchOnMount = true }: CartProviderProps) {
+  const shop = useShop();
+  const [cart, setCart] = React.useState<Cart | null>(null);
+  const [status, setStatus] = React.useState<CartStatus>('uninitialized');
+  const [error, setError] = React.useState<string | null>(null);
+  const listenersRef = React.useRef(new Set<(c: Cart | null) => void>());
+
+  const gql = React.useCallback(
+    async <T = any>(query: string, variables?: any): Promise<T> => {
+      const res = await fetch(shop.apiUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Storefront-Access-Token': shop.storefrontAccessToken,
+        },
+        body: JSON.stringify({ query, variables }),
+        credentials: 'include',
+      });
+      const json: any = await res.json();
+      if (json.errors) throw new Error(json.errors[0]?.message || 'GraphQL error');
+      return json.data;
+    },
+    [shop.apiUrl, shop.storefrontAccessToken],
+  );
+
+  const notifyListeners = React.useCallback((c: Cart | null) => {
+    for (const fn of listenersRef.current) fn(c);
+  }, []);
+
+  // 应用新 cart 数据（state + 订阅者）
+  const applyCart = React.useCallback(
+    (next: Cart | null) => {
+      setCart(next);
+      notifyListeners(next);
+    },
+    [notifyListeners],
+  );
+
+  // 保证有 cart_id，没有就创建
+  const ensureCartId = React.useCallback(async (): Promise<string> => {
+    const cookieCartId = readCartIdFromCookie();
+    if (cookieCartId) return cookieCartId;
+    const data = await gql<{ cartCreate: { cart: Cart; userErrors: CartUserError[] } }>(
+      M_CART_CREATE,
+      { input: { lines: [] } },
+    );
+    if (data.cartCreate.userErrors.length > 0) {
+      throw new Error(data.cartCreate.userErrors[0].message);
+    }
+    const newCart = data.cartCreate.cart;
+    saveCartIdToCookie(newCart.id);
+    applyCart(newCart);
+    return newCart.id;
+  }, [gql, applyCart]);
+
+  // 初始拉取
+  const refetch = React.useCallback(async () => {
+    setStatus('loading');
+    try {
+      const cookieCartId = readCartIdFromCookie();
+      if (!cookieCartId) {
+        applyCart(null);
+        setStatus('idle');
+        return;
+      }
+      const data = await gql<{ cart: Cart | null }>(Q_GET_CART, { id: cookieCartId });
+      applyCart(data.cart);
+      setStatus('idle');
+    } catch (err: any) {
+      setError(err?.message ?? String(err));
+      setStatus('error');
+    }
+  }, [gql, applyCart]);
+
+  React.useEffect(() => {
+    if (fetchOnMount && status === 'uninitialized') {
+      void refetch();
+    }
+  }, [fetchOnMount, status, refetch]);
+
+  // optimistic 包装
+  const runMutation = React.useCallback(
+    async <T,>(optimisticCart: Cart | null, mutator: () => Promise<{ cart: Cart; userErrors: CartUserError[] }>) => {
+      const prev = cart;
+      if (optimisticCart) applyCart(optimisticCart);
+      setStatus('updating');
+      try {
+        const result = await mutator();
+        if (result.userErrors && result.userErrors.length > 0) {
+          throw new Error(result.userErrors[0].message);
+        }
+        applyCart(result.cart);
+        setStatus('idle');
+        setError(null);
+      } catch (err: any) {
+        applyCart(prev); // 回滚
+        setError(err?.message ?? String(err));
+        setStatus('error');
+        throw err;
+      }
+    },
+    [cart, applyCart],
+  );
+
+  const linesAdd = React.useCallback(
+    async (lines: Array<{ merchandiseId: string; quantity?: number }>) => {
+      const cartId = await ensureCartId();
+      await runMutation(null, async () => {
+        const data = await gql<{ cartLinesAdd: { cart: Cart; userErrors: CartUserError[] } }>(
+          M_LINES_ADD,
+          {
+            cartId,
+            lines: lines.map((l) => ({ merchandiseId: l.merchandiseId, quantity: l.quantity ?? 1 })),
+          },
+        );
+        return data.cartLinesAdd;
+      });
+    },
+    [ensureCartId, runMutation, gql],
+  );
+
+  const linesUpdate = React.useCallback(
+    async (lines: Array<{ id: string; quantity: number }>) => {
+      // remove 走 remove
+      const toRemove = lines.filter((l) => l.quantity <= 0).map((l) => l.id);
+      const toUpdate = lines.filter((l) => l.quantity > 0);
+
+      // optimistic: 改 quantity
+      const optimistic =
+        cart != null
+          ? {
+              ...cart,
+              lines: {
+                ...cart.lines,
+                nodes: cart.lines.nodes
+                  .map((ln) => {
+                    const upd = toUpdate.find((l) => l.id === ln.id);
+                    return upd ? { ...ln, quantity: upd.quantity } : ln;
+                  })
+                  .filter((ln) => !toRemove.includes(ln.id)),
+              },
+            }
+          : null;
+
+      const cartId = await ensureCartId();
+      await runMutation(optimistic, async () => {
+        if (toRemove.length > 0) {
+          await gql(M_LINES_REMOVE, { cartId, lineIds: toRemove });
+        }
+        if (toUpdate.length === 0) {
+          const data = await gql<{ cart: Cart }>(Q_GET_CART, { id: cartId });
+          return { cart: data.cart!, userErrors: [] };
+        }
+        const data = await gql<{ cartLinesUpdate: { cart: Cart; userErrors: CartUserError[] } }>(
+          M_LINES_UPDATE,
+          { cartId, lines: toUpdate },
+        );
+        return data.cartLinesUpdate;
+      });
+    },
+    [cart, ensureCartId, runMutation, gql],
+  );
+
+  const linesRemove = React.useCallback(
+    async (lineIds: string[]) => {
+      const optimistic =
+        cart != null
+          ? {
+              ...cart,
+              lines: { ...cart.lines, nodes: cart.lines.nodes.filter((l) => !lineIds.includes(l.id)) },
+            }
+          : null;
+
+      const cartId = await ensureCartId();
+      await runMutation(optimistic, async () => {
+        const data = await gql<{ cartLinesRemove: { cart: Cart; userErrors: CartUserError[] } }>(
+          M_LINES_REMOVE,
+          { cartId, lineIds },
+        );
+        return data.cartLinesRemove;
+      });
+    },
+    [cart, ensureCartId, runMutation, gql],
+  );
+
+  const subscribe = React.useCallback((listener: (c: Cart | null) => void) => {
+    listenersRef.current.add(listener);
+    return () => {
+      listenersRef.current.delete(listener);
+    };
+  }, []);
+
+  const value: CartContextValue = React.useMemo(
+    () => ({ cart, status, error, linesAdd, linesUpdate, linesRemove, refetch, subscribe }),
+    [cart, status, error, linesAdd, linesUpdate, linesRemove, refetch, subscribe],
+  );
+
+  return <CartContext.Provider value={value}>{children}</CartContext.Provider>;
+}
+
+/**
+ * 拿 cart context。Provider 外 throw。
+ */
+export function useCart(): CartContextValue {
+  const v = React.useContext(CartContext);
+  if (!v) throw new Error('useCart must be used inside <CartProvider>');
+  return v;
+}
+
+/**
+ * 非 throw 版本：Provider 外返回 null。
+ * 给可选 fallback 用，比如 <AddToCartButton> 在没 Provider 时退化到 props.onAdd。
+ */
+export function useCartOptional(): CartContextValue | null {
+  return React.useContext(CartContext);
+}