@shopbb/helium 0.2.0 → 0.3.0-alpha.2

package/dist/components/ProductPrice.d.ts

@@ -0,0 +1,28 @@
+/**
+ * <ProductPrice> — 商品价格
+ *
+ * 对齐 @shopify/hydrogen <ProductPrice>:
+ *   - 渲染当前价
+ *   - 当 compareAtPrice > price 时自动显示划线对比价
+ *   - 支持 unit price 模式
+ *   - 可定制 className / 容器
+ *
+ * 用法：
+ *   <ProductPrice price={{ amount: '99', currencyCode: 'CNY' }} />
+ *   <ProductPrice price={...} compareAtPrice={{ amount: '129', ... }} />
+ */
+import * as React from 'react';
+import { type MoneyData, type MoneyMeasurement } from './Money';
+export interface ProductPriceProps extends React.HTMLAttributes<HTMLElement> {
+    price: MoneyData;
+    compareAtPrice?: MoneyData | null;
+    /** unit price，例如每 100g */
+    measurement?: MoneyMeasurement;
+    /** locale 透传 */
+    locale?: string;
+    /** 划线价的额外 className */
+    compareAtClassName?: string;
+    as?: keyof JSX.IntrinsicElements;
+}
+export declare function ProductPrice(props: ProductPriceProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ProductPrice.d.ts.map

package/dist/components/ProductPrice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProductPrice.d.ts","sourceRoot":"","sources":["../../src/components/ProductPrice.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAS,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEvE,MAAM,WAAW,iBAAkB,SAAQ,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC;IAC1E,KAAK,EAAE,SAAS,CAAC;IACjB,cAAc,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC,0BAA0B;IAC1B,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,gBAAgB;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,iBAAiB,CAAC;CAClC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,2CA+BpD"}

package/dist/components/ProductPrice.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Money } from './Money';
+export function ProductPrice(props) {
+    const { price, compareAtPrice, measurement, locale, compareAtClassName, as, ...rest } = props;
+    const Tag = as || 'div';
+    const hasDiscount = compareAtPrice &&
+        Number(compareAtPrice.amount) > Number(price.amount);
+    return (_jsxs(Tag, { ...rest, "data-product-price": true, children: [_jsx(Money, { data: price, locale: locale, measurement: measurement }), hasDiscount && compareAtPrice && (_jsx(Money, { data: compareAtPrice, locale: locale, as: "s", className: compareAtClassName, "data-compare-at": "true", style: { marginLeft: '0.5em', opacity: 0.6 } }))] }));
+}
+//# sourceMappingURL=ProductPrice.js.map

package/dist/components/ProductPrice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProductPrice.js","sourceRoot":"","sources":["../../src/components/ProductPrice.tsx"],"names":[],"mappings":";AAeA,OAAO,EAAE,KAAK,EAAyC,MAAM,SAAS,CAAC;AAcvE,MAAM,UAAU,YAAY,CAAC,KAAwB;IACnD,MAAM,EACJ,KAAK,EACL,cAAc,EACd,WAAW,EACX,MAAM,EACN,kBAAkB,EAClB,EAAE,EACF,GAAG,IAAI,EACR,GAAG,KAAK,CAAC;IAEV,MAAM,GAAG,GAAQ,EAAE,IAAI,KAAK,CAAC;IAC7B,MAAM,WAAW,GACf,cAAc;QACd,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAEvD,OAAO,CACL,MAAC,GAAG,OAAK,IAAI,yCACX,KAAC,KAAK,IAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAI,EAC/D,WAAW,IAAI,cAAc,IAAI,CAChC,KAAC,KAAK,IACJ,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM,EACd,EAAE,EAAC,GAAG,EACN,SAAS,EAAE,kBAAkB,qBACb,MAAM,EACtB,KAAK,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,GAC5C,CACH,IACG,CACP,CAAC;AACJ,CAAC"}

package/dist/components/ShopProvider.d.ts

@@ -0,0 +1,49 @@
+/**
+ * <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>;
+}
+export interface ShopProviderProps extends Partial<ShopContextValue> {
+    storeId: string;
+    storefrontAccessToken: string;
+    apiUrl: string;
+    children: React.ReactNode;
+}
+export declare function ShopProvider(props: ShopProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * 拿当前 shop context。Provider 外调用会 throw。
+ */
+export declare function useShop(): ShopContextValue;
+/**
+ * 非 throw 版本：Provider 外返回 null。
+ * 给组件做"可选 fallback"用，比如 <Money> 在没 ShopProvider 时也要能跑。
+ */
+export declare function useShopOptional(): ShopContextValue | null;
+//# sourceMappingURL=ShopProvider.d.ts.map

package/dist/components/ShopProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShopProvider.d.ts","sourceRoot":"","sources":["../../src/components/ShopProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAID,MAAM,WAAW,iBAAkB,SAAQ,OAAO,CAAC,gBAAgB,CAAC;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,2CAsBpD;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,gBAAgB,CAM1C;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,GAAG,IAAI,CAEzD"}

package/dist/components/ShopProvider.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * <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';
+const ShopContext = React.createContext(null);
+export function ShopProvider(props) {
+    const value = React.useMemo(() => ({
+        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 _jsx(ShopContext.Provider, { value: value, children: props.children });
+}
+/**
+ * 拿当前 shop context。Provider 外调用会 throw。
+ */
+export function useShop() {
+    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() {
+    return React.useContext(ShopContext);
+}
+//# sourceMappingURL=ShopProvider.js.map

package/dist/components/ShopProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShopProvider.js","sourceRoot":"","sources":["../../src/components/ShopProvider.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAa/B,MAAM,WAAW,GAAG,KAAK,CAAC,aAAa,CAA0B,IAAI,CAAC,CAAC;AASvE,MAAM,UAAU,YAAY,CAAC,KAAwB;IACnD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CACzB,GAAG,EAAE,CAAC,CAAC;QACL,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,qBAAqB,EAAE,KAAK,CAAC,qBAAqB;QAClD,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,EAAE;QAC9B,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,KAAK;QACzC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,OAAO;QAC/B,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC,EACF;QACE,KAAK,CAAC,OAAO;QACb,KAAK,CAAC,qBAAqB;QAC3B,KAAK,CAAC,MAAM;QACZ,KAAK,CAAC,QAAQ;QACd,KAAK,CAAC,YAAY;QAClB,KAAK,CAAC,MAAM;QACZ,KAAK,CAAC,IAAI;KACX,CACF,CAAC;IACF,OAAO,KAAC,WAAW,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,KAAK,CAAC,QAAQ,GAAwB,CAAC;AACrF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO;IACrB,MAAM,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AACvC,CAAC"}

package/dist/components/VariantSelector.d.ts

@@ -0,0 +1,80 @@
+/**
+ * <VariantSelector> — 商品 variant 选择器
+ *
+ * 对齐 @shopify/hydrogen <VariantSelector>:
+ *   - 自动解析 variants 的 selectedOptions 维度（颜色 / 尺寸 等）
+ *   - 渲染每个维度的选项按钮
+ *   - 不可购买组合 disabled
+ *   - URL 同步（可选）
+ *   - 默认选第一个 availableForSale
+ *
+ * 设计：组件用 render prop，把每个 option 的选项交给商家渲染。
+ *
+ * 用法：
+ *   <VariantSelector
+ *     product={product}
+ *     value={selectedVariantId}
+ *     onChange={setSelectedVariantId}
+ *   >
+ *     {({ option, value, onSelect }) => (
+ *       <div>
+ *         <h4>{option.name}</h4>
+ *         {option.values.map((v) => (
+ *           <button
+ *             key={v.value}
+ *             disabled={!v.available}
+ *             onClick={() => onSelect(v.value)}
+ *             aria-pressed={v.value === value}
+ *           >
+ *             {v.value}
+ *           </button>
+ *         ))}
+ *       </div>
+ *     )}
+ *   </VariantSelector>
+ */
+import * as React from 'react';
+interface SelectedOption {
+    name: string;
+    value: string;
+}
+interface ProductVariant {
+    id: string;
+    availableForSale: boolean;
+    selectedOptions?: SelectedOption[];
+}
+interface ProductLike {
+    options?: Array<{
+        name: string;
+        values: string[];
+    }>;
+    variants: {
+        nodes: ProductVariant[];
+    };
+}
+export interface VariantOption {
+    name: string;
+    values: Array<{
+        value: string;
+        available: boolean;
+    }>;
+}
+export interface VariantSelectorRenderProps {
+    option: VariantOption;
+    /** 当前已选择的 value（在这个 option 维度上） */
+    value: string | undefined;
+    /** 选择 value，触发 onChange 更新 selectedVariantId */
+    onSelect: (value: string) => void;
+}
+export interface VariantSelectorProps {
+    product: ProductLike;
+    /** 当前选中 variant 的 GID */
+    value: string;
+    /** variant 切换时调用 */
+    onChange?: (variantId: string) => void;
+    /** 每个 option 的渲染函数 */
+    children: (renderProps: VariantSelectorRenderProps) => React.ReactNode;
+}
+export declare function VariantSelector(props: VariantSelectorProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=VariantSelector.d.ts.map

package/dist/components/VariantSelector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VariantSelector.d.ts","sourceRoot":"","sources":["../../src/components/VariantSelector.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,cAAc;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACpC;AAED,UAAU,WAAW;IACnB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACpD,QAAQ,EAAE;QAAE,KAAK,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,aAAa,CAAC;IACtB,mCAAmC;IACnC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,WAAW,CAAC;IACrB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,sBAAsB;IACtB,QAAQ,EAAE,CAAC,WAAW,EAAE,0BAA0B,KAAK,KAAK,CAAC,SAAS,CAAC;CACxE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,2CAsE1D"}

package/dist/components/VariantSelector.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * <VariantSelector> — 商品 variant 选择器
+ *
+ * 对齐 @shopify/hydrogen <VariantSelector>:
+ *   - 自动解析 variants 的 selectedOptions 维度（颜色 / 尺寸 等）
+ *   - 渲染每个维度的选项按钮
+ *   - 不可购买组合 disabled
+ *   - URL 同步（可选）
+ *   - 默认选第一个 availableForSale
+ *
+ * 设计：组件用 render prop，把每个 option 的选项交给商家渲染。
+ *
+ * 用法：
+ *   <VariantSelector
+ *     product={product}
+ *     value={selectedVariantId}
+ *     onChange={setSelectedVariantId}
+ *   >
+ *     {({ option, value, onSelect }) => (
+ *       <div>
+ *         <h4>{option.name}</h4>
+ *         {option.values.map((v) => (
+ *           <button
+ *             key={v.value}
+ *             disabled={!v.available}
+ *             onClick={() => onSelect(v.value)}
+ *             aria-pressed={v.value === value}
+ *           >
+ *             {v.value}
+ *           </button>
+ *         ))}
+ *       </div>
+ *     )}
+ *   </VariantSelector>
+ */
+import * as React from 'react';
+export function VariantSelector(props) {
+    const { product, value, onChange, children } = props;
+    const variants = product.variants.nodes;
+    const currentVariant = variants.find((v) => v.id === value) || variants[0];
+    // 推断 options（如果 product.options 没传，从 variants.selectedOptions 提取）
+    const options = React.useMemo(() => {
+        if (product.options && product.options.length > 0) {
+            return product.options.map((opt) => ({
+                name: opt.name,
+                values: opt.values.map((v) => ({
+                    value: v,
+                    available: variants.some((variant) => variant.availableForSale &&
+                        variant.selectedOptions?.some((so) => so.name === opt.name && so.value === v)),
+                })),
+            }));
+        }
+        // 从 variants.selectedOptions 反推
+        const dimMap = new Map();
+        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, values]) => ({
+            name,
+            values: Array.from(values).map((v) => ({
+                value: v,
+                available: variants.some((variant) => variant.availableForSale &&
+                    variant.selectedOptions?.some((so) => so.name === name && so.value === v)),
+            })),
+        }));
+    }, [product, variants]);
+    // 切换某 option 的 value：找一个匹配的 variant
+    const handleSelect = (optionName, optionValue) => {
+        const currentSelected = new Map((currentVariant?.selectedOptions ?? []).map((so) => [so.name, so.value]));
+        currentSelected.set(optionName, optionValue);
+        // 找最匹配 + available 的 variant
+        const target = variants.find((v) => Array.from(currentSelected.entries()).every(([n, val]) => v.selectedOptions?.some((so) => so.name === n && so.value === val)));
+        if (target)
+            onChange?.(target.id);
+    };
+    return (_jsx(_Fragment, { children: options.map((option) => (_jsx(React.Fragment, { children: children({
+                option,
+                value: currentVariant?.selectedOptions?.find((so) => so.name === option.name)?.value,
+                onSelect: (val) => handleSelect(option.name, val),
+            }) }, option.name))) }));
+}
+//# sourceMappingURL=VariantSelector.js.map

package/dist/components/VariantSelector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VariantSelector.js","sourceRoot":"","sources":["../../src/components/VariantSelector.tsx"],"names":[],"mappings":"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"}

package/dist/components/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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
+ */
+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';
+export { Image } from './Image';
+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, VariantSelectorRenderProps, VariantOption, } from './VariantSelector';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxE,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE1E,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxE,YAAY,EACV,IAAI,EACJ,QAAQ,EACR,mBAAmB,EACnB,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACjF,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAGzG,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEvE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,YAAY,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AAExF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,aAAa,GACd,MAAM,mBAAmB,CAAC"}

package/dist/components/index.js

@@ -0,0 +1,33 @@
+/**
+ * @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
+ */
+// Providers + hooks
+export { ShopProvider, useShop, useShopOptional } from './ShopProvider';
+export { CartProvider, useCart, useCartOptional } from './CartProvider';
+export { ProductOptionsProvider, useProductOptions, } from './ProductOptionsProvider';
+export { AnalyticsProvider, useAnalytics, Analytics } from './AnalyticsProvider';
+// 展示型组件
+export { Money } from './Money';
+export { Image } from './Image';
+export { ProductPrice } from './ProductPrice';
+export { AddToCartButton } from './AddToCartButton';
+export { CartLineQuantityAdjustButton } from './CartLineQuantityAdjustButton';
+export { VariantSelector } from './VariantSelector';
+//# sourceMappingURL=index.js.map

package/dist/components/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAWxE,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAOlC,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGjF,QAAQ;AACR,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAG9E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shopbb/helium",
-  "version": "0.2.0",
-  "description": "shopbb storefront framework — GraphQL client, cart handler, cache helpers, and React SSR for Cloudflare Workers",
+  "version": "0.3.0-alpha.2",
+  "description": "shopbb storefront framework — components, React SSR, GraphQL client, cart handler, cache for Cloudflare Workers",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -20,6 +20,10 @@
     "./client": {
       "types": "./dist/client.d.ts",
       "import": "./dist/client.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js"
     }
   },
   "files": [
@@ -48,8 +52,12 @@
     "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true },
-    "react-dom": { "optional": true }
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20240117.0",

package/src/components/AddToCartButton.tsx

@@ -0,0 +1,101 @@
+/**
+ * <AddToCartButton> — 加入购物车按钮
+ *
+ * 对齐 @shopify/hydrogen <AddToCartButton>：
+ *   - 内置 loading 态、disabled、error 处理
+ *   - 支持 onAdd 回调（实际加购逻辑由外部 cart hook 提供）
+ *   - 触发 analytics 事件钩子
+ *   - 不带样式，商家自己控制
+ *
+ * 用法（Phase 1，需要传 onAdd）：
+ *   const { addLine } = useCart();
+ *   <AddToCartButton
+ *     variantId={selectedVariant.id}
+ *     quantity={1}
+ *     disabled={!selectedVariant.availableForSale}
+ *     onAdd={(vid, qty) => addLine(vid, qty)}
+ *   >
+ *     加入购物车
+ *   </AddToCartButton>
+ *
+ * Phase 2 后：组件会自动从 <CartProvider> 拿，无需 onAdd 也能用。
+ */
+
+import * as React from 'react';
+import { useCartOptional } from './CartProvider';
+import { useAnalytics } from './AnalyticsProvider';
+
+export interface AddToCartButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'onError'> {
+  /** 必传：variant 的 GID（gid://shopbb/ProductVariant/...） */
+  variantId: string;
+  /** 数量，默认 1 */
+  quantity?: number;
+  /** 实际加购回调。Phase 1 必传；Phase 2 后可从 Provider 自动获取 */
+  onAdd?: (variantId: string, quantity: number) => Promise<void>;
+  /** 加购成功回调（如导航到 /cart） */
+  onAdded?: () => void;
+  /** 加购失败回调 */
+  onError?: (err: Error) => void;
+  /** 加购中显示的文本，默认 "加入中..." */
+  loadingText?: React.ReactNode;
+  /** 不可用时显示的文本，默认 "缺货" */
+  unavailableText?: React.ReactNode;
+}
+
+export function AddToCartButton(props: AddToCartButtonProps) {
+  const {
+    variantId,
+    quantity = 1,
+    onAdd,
+    onAdded,
+    onError,
+    loadingText = '加入中...',
+    unavailableText = '缺货',
+    children = '加入购物车',
+    disabled: disabledProp,
+    ...rest
+  } = props;
+
+  const [adding, setAdding] = React.useState(false);
+  const cart = useCartOptional();
+  const analytics = useAnalytics();
+
+  const handleClick = async (e: React.MouseEvent<HTMLButtonElement>) => {
+    e.preventDefault();
+    if (adding || disabledProp) return;
+
+    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;
+      }
+      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);
+    }
+  };
+
+  return (
+    <button
+      type="button"
+      {...rest}
+      data-add-to-cart
+      data-loading={adding ? '' : undefined}
+      disabled={disabledProp || adding}
+      onClick={handleClick}
+    >
+      {adding ? loadingText : disabledProp ? unavailableText : children}
+    </button>
+  );
+}