@shopbb/helium 0.3.0-alpha.1 → 0.3.0

package/src/components/ProductOptionsProvider.tsx

@@ -0,0 +1,149 @@
+/**
+ * <ProductOptionsProvider> + useProductOptions()
+ *
+ * 给商品详情页用。包住 product 后，自动管理 selectedVariantId 状态 +
+ * 暴露当前 variant、available options、setOption 等。
+ *
+ * 用法：
+ *   <ProductOptionsProvider product={product}>
+ *     <ProductDetailBody />
+ *   </ProductOptionsProvider>
+ *
+ *   function ProductDetailBody() {
+ *     const { selectedVariant, options, setOptionValue } = useProductOptions();
+ *     return ...;
+ *   }
+ */
+
+import * as React from 'react';
+
+interface SelectedOption { name: string; value: string; }
+
+interface ProductVariantLike {
+  id: string;
+  availableForSale: boolean;
+  selectedOptions?: SelectedOption[];
+  price?: { amount: string; currencyCode: string };
+  compareAtPrice?: { amount: string; currencyCode: string } | null;
+}
+
+interface ProductLike {
+  id: string;
+  options?: Array<{ name: string; values: string[] }>;
+  variants: { nodes: ProductVariantLike[] };
+}
+
+export interface ProductOptionItem {
+  name: string;
+  values: Array<{ value: string; available: boolean; isSelected: boolean }>;
+}
+
+export interface ProductOptionsContextValue {
+  product: ProductLike;
+  selectedVariant: ProductVariantLike | null;
+  selectedOptions: Record<string, string>;
+  options: ProductOptionItem[];
+  setOptionValue: (name: string, value: string) => void;
+  setVariantById: (variantId: string) => void;
+}
+
+const Ctx = React.createContext<ProductOptionsContextValue | null>(null);
+
+export interface ProductOptionsProviderProps {
+  product: ProductLike;
+  /** 初始 selectedVariantId；默认第一个可购 variant */
+  initialVariantId?: string;
+  children: React.ReactNode;
+}
+
+export function ProductOptionsProvider(props: ProductOptionsProviderProps) {
+  const { product, initialVariantId, children } = props;
+  const variants = product.variants.nodes;
+
+  const findDefault = React.useCallback(() => {
+    if (initialVariantId) {
+      const found = variants.find((v) => v.id === initialVariantId);
+      if (found) return found;
+    }
+    return variants.find((v) => v.availableForSale) ?? variants[0] ?? null;
+  }, [initialVariantId, variants]);
+
+  const [selectedVariantId, setSelectedVariantId] = React.useState<string | null>(
+    findDefault()?.id ?? null,
+  );
+
+  React.useEffect(() => {
+    setSelectedVariantId(findDefault()?.id ?? null);
+  }, [findDefault]);
+
+  const selectedVariant =
+    variants.find((v) => v.id === selectedVariantId) ?? null;
+
+  const selectedOptions: Record<string, string> = React.useMemo(() => {
+    const m: Record<string, string> = {};
+    for (const so of selectedVariant?.selectedOptions ?? []) m[so.name] = so.value;
+    return m;
+  }, [selectedVariant]);
+
+  const options: ProductOptionItem[] = React.useMemo(() => {
+    const dimMap = new Map<string, Set<string>>();
+    // 收集所有 option 维度
+    if (product.options?.length) {
+      for (const opt of product.options) {
+        dimMap.set(opt.name, new Set(opt.values));
+      }
+    } else {
+      for (const v of variants) {
+        for (const so of v.selectedOptions ?? []) {
+          if (!dimMap.has(so.name)) dimMap.set(so.name, new Set());
+          dimMap.get(so.name)!.add(so.value);
+        }
+      }
+    }
+    return Array.from(dimMap.entries()).map(([name, vals]) => ({
+      name,
+      values: Array.from(vals).map((v) => ({
+        value: v,
+        available: variants.some(
+          (variant) =>
+            variant.availableForSale &&
+            variant.selectedOptions?.some((so) => so.name === name && so.value === v),
+        ),
+        isSelected: selectedOptions[name] === v,
+      })),
+    }));
+  }, [product, variants, selectedOptions]);
+
+  const setOptionValue = React.useCallback(
+    (name: string, value: string) => {
+      const next = { ...selectedOptions, [name]: value };
+      // 找匹配 variant
+      const target = variants.find((v) =>
+        Object.entries(next).every(([n, val]) =>
+          v.selectedOptions?.some((so) => so.name === n && so.value === val),
+        ),
+      );
+      if (target) setSelectedVariantId(target.id);
+    },
+    [selectedOptions, variants],
+  );
+
+  const setVariantById = React.useCallback((id: string) => setSelectedVariantId(id), []);
+
+  const value: ProductOptionsContextValue = {
+    product,
+    selectedVariant,
+    selectedOptions,
+    options,
+    setOptionValue,
+    setVariantById,
+  };
+
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+}
+
+export function useProductOptions(): ProductOptionsContextValue {
+  const v = React.useContext(Ctx);
+  if (!v) throw new Error('useProductOptions must be used inside <ProductOptionsProvider>');
+  return v;
+}

package/src/components/ShopProvider.tsx

@@ -0,0 +1,86 @@
+/**
+ * <ShopProvider> + useShop()
+ *
+ * 全局店铺上下文 — 注入 storefront token / apiUrl / 货币 / locale / shop 元信息。
+ * 子组件用 useShop() 直接拿，不用 prop-drill。
+ *
+ * 用法：
+ *   <ShopProvider
+ *     storeId="store_xxx"
+ *     storefrontAccessToken="shpat_pub_..."
+ *     apiUrl="https://api.example.com/api/2026-04/graphql.json"
+ *     shopName="Shopflare"
+ *     currencyCode="CNY"
+ *     locale="zh-CN"
+ *   >
+ *     <App />
+ *   </ShopProvider>
+ *
+ *   // 任意子组件：
+ *   const { storeId, storefrontAccessToken } = useShop();
+ */
+
+import * as React from 'react';
+
+export interface ShopContextValue {
+  storeId: string;
+  storefrontAccessToken: string;
+  apiUrl: string;
+  shopName: string;
+  currencyCode: string;
+  locale: string;
+  /** 额外自定义字段，用户可塞任意业务 meta */
+  meta?: Record<string, any>;
+}
+
+const ShopContext = React.createContext<ShopContextValue | null>(null);
+
+export interface ShopProviderProps extends Partial<ShopContextValue> {
+  storeId: string;
+  storefrontAccessToken: string;
+  apiUrl: string;
+  children: React.ReactNode;
+}
+
+export function ShopProvider(props: ShopProviderProps) {
+  const value = React.useMemo<ShopContextValue>(
+    () => ({
+      storeId: props.storeId,
+      storefrontAccessToken: props.storefrontAccessToken,
+      apiUrl: props.apiUrl,
+      shopName: props.shopName ?? '',
+      currencyCode: props.currencyCode ?? 'USD',
+      locale: props.locale ?? 'en-US',
+      meta: props.meta,
+    }),
+    [
+      props.storeId,
+      props.storefrontAccessToken,
+      props.apiUrl,
+      props.shopName,
+      props.currencyCode,
+      props.locale,
+      props.meta,
+    ],
+  );
+  return <ShopContext.Provider value={value}>{props.children}</ShopContext.Provider>;
+}
+
+/**
+ * 拿当前 shop context。Provider 外调用会 throw。
+ */
+export function useShop(): ShopContextValue {
+  const v = React.useContext(ShopContext);
+  if (!v) {
+    throw new Error('useShop must be used inside <ShopProvider>');
+  }
+  return v;
+}
+
+/**
+ * 非 throw 版本：Provider 外返回 null。
+ * 给组件做"可选 fallback"用，比如 <Money> 在没 ShopProvider 时也要能跑。
+ */
+export function useShopOptional(): ShopContextValue | null {
+  return React.useContext(ShopContext);
+}

package/src/components/index.ts

@@ -2,14 +2,52 @@
  * @shopbb/helium/components — 商家用 React 组件
  *
  * 用法：
- *   import { Money, Image, ProductPrice, AddToCartButton } from '@shopbb/helium/components';
+ *   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
  */
 
+// Providers + hooks
+export { ShopProvider, useShop, useShopOptional } from './ShopProvider';
+export type { ShopContextValue, ShopProviderProps } from './ShopProvider';
+
+export { CartProvider, useCart, useCartOptional } from './CartProvider';
+export type {
+  Cart,
+  CartLine,
+  CartLineMerchandise,
+  CartStatus,
+  CartUserError,
+  CartContextValue,
+  CartProviderProps,
+} from './CartProvider';
+
+export {
+  ProductOptionsProvider,
+  useProductOptions,
+} from './ProductOptionsProvider';
+export type {
+  ProductOptionsContextValue,
+  ProductOptionsProviderProps,
+  ProductOptionItem,
+} from './ProductOptionsProvider';
+
+export { AnalyticsProvider, useAnalytics, Analytics } from './AnalyticsProvider';
+export type { AnalyticsEvent, AnalyticsContextValue, AnalyticsProviderProps } from './AnalyticsProvider';
+
+// 展示型组件
 export { Money } from './Money';
 export type { MoneyProps, MoneyData, MoneyMeasurement } from './Money';