@shopbb/helium 0.2.0 → 0.3.0-alpha.1

package/dist/components/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @shopbb/helium/components — 商家用 React 组件
+ *
+ * 用法：
+ *   import { Money, Image, ProductPrice, AddToCartButton } from '@shopbb/helium/components';
+ *
+ * 设计原则：
+ *   - 无样式：组件只管行为 + 语义化 DOM，样式商家自己写
+ *   - data-* 钩子：方便选择器
+ *   - 对齐 Shopify Hydrogen 同名组件的 API，迁移成本低
+ */
+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;;;;;;;;;;GAUG;AAEH,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,18 @@
+/**
+ * @shopbb/helium/components — 商家用 React 组件
+ *
+ * 用法：
+ *   import { Money, Image, ProductPrice, AddToCartButton } from '@shopbb/helium/components';
+ *
+ * 设计原则：
+ *   - 无样式：组件只管行为 + 语义化 DOM，样式商家自己写
+ *   - data-* 钩子：方便选择器
+ *   - 对齐 Shopify Hydrogen 同名组件的 API，迁移成本低
+ */
+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;;;;;;;;;;GAUG;AAEH,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.1",
+  "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,90 @@
+/**
+ * <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';
+
+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 handleClick = async (e: React.MouseEvent<HTMLButtonElement>) => {
+    e.preventDefault();
+    if (adding || disabledProp) return;
+    if (!onAdd) {
+      console.warn('[AddToCartButton] onAdd not provided; this button does nothing in Phase 1');
+      return;
+    }
+    setAdding(true);
+    try {
+      await onAdd(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>
+  );
+}

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/Image.tsx

@@ -0,0 +1,93 @@
+/**
+ * <Image> — 响应式商品图片
+ *
+ * 对齐 @shopify/hydrogen 的 <Image>：
+ *   - 自动生成 srcset（5 个分辨率档：375 / 750 / 1024 / 1536 / 1920）
+ *   - sizes 媒体查询
+ *   - loading="lazy" 默认（首屏可关）
+ *   - decoding="async"
+ *   - aspectRatio 占位（不抖）
+ *   - 自动 alt
+ *
+ * srcset 里的 url 通过 ?width= query 表达，服务端可忽略或接 cdn-cgi/image。
+ *
+ * 用法：
+ *   <Image data={{ url, altText, width, height }} sizes="(min-width: 768px) 50vw, 100vw" />
+ *   <Image data={...} aspectRatio="1/1" />
+ *   <Image data={...} loading="eager" />   // 首屏
+ */
+
+import * as React from 'react';
+
+export interface ImageData {
+  url: string;
+  altText?: string | null;
+  width?: number | null;
+  height?: number | null;
+}
+
+export interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, 'src' | 'srcSet' | 'loading'> {
+  /** 必传：图片对象 */
+  data: ImageData;
+  /** 媒体查询 sizes，例如 (min-width: 768px) 50vw, 100vw */
+  sizes?: string;
+  /** 强制宽高比，例如 '1/1' '4/3' '16/9' */
+  aspectRatio?: string;
+  /** lazy（默认） / eager（首屏图用） */
+  loading?: 'lazy' | 'eager';
+  /** 自定义 srcset 档位 */
+  widths?: number[];
+}
+
+// 默认 srcset 档位
+const DEFAULT_WIDTHS = [375, 750, 1024, 1536, 1920];
+
+/** 给 url 加 ?width=N query */
+function withWidth(url: string, width: number): string {
+  try {
+    const u = new URL(url);
+    u.searchParams.set('width', String(width));
+    return u.toString();
+  } catch {
+    // 不是绝对 URL，按相对路径处理
+    const sep = url.includes('?') ? '&' : '?';
+    return `${url}${sep}width=${width}`;
+  }
+}
+
+export function Image(props: ImageProps) {
+  const {
+    data,
+    sizes,
+    aspectRatio,
+    loading = 'lazy',
+    widths = DEFAULT_WIDTHS,
+    style,
+    alt: altProp,
+    ...rest
+  } = props;
+
+  const srcset = widths.map((w) => `${withWidth(data.url, w)} ${w}w`).join(', ');
+  // src 用中间档位
+  const src = withWidth(data.url, widths[Math.floor(widths.length / 2)]);
+
+  const finalStyle: React.CSSProperties = {
+    ...(aspectRatio ? { aspectRatio, objectFit: 'cover' as const } : null),
+    ...style,
+  };
+
+  return (
+    <img
+      {...rest}
+      src={src}
+      srcSet={srcset}
+      sizes={sizes}
+      alt={altProp ?? data.altText ?? ''}
+      loading={loading}
+      decoding="async"
+      width={data.width || undefined}
+      height={data.height || undefined}
+      style={finalStyle}
+    />
+  );
+}

package/src/components/Money.tsx

@@ -0,0 +1,106 @@
+/**
+ * <Money> — 货币格式化
+ *
+ * 对齐 @shopify/hydrogen 的 <Money>。
+ * - 自动按 currencyCode + locale 用 Intl.NumberFormat 格式化
+ * - 支持 withoutCurrency / withoutTrailingZeros
+ * - 支持 as 渲染成任意元素（默认 <span>）
+ * - 支持 measurement（unit price，例如 ¥9.99/100g）
+ *
+ * 用法：
+ *   <Money data={{ amount: '9.99', currencyCode: 'CNY' }} />
+ *   <Money data={{ ... }} withoutCurrency />
+ *   <Money data={{ ... }} as="div" measurement={{ referenceUnit: 'kg', quantity: 0.1 }} />
+ */
+
+import * as React from 'react';
+
+export interface MoneyData {
+  amount: string;
+  currencyCode: string;
+}
+
+export interface MoneyMeasurement {
+  /** 比如 'kg' / '100g' / 'l' */
+  referenceUnit: string;
+  /** 比如 0.1 表示每 100g */
+  quantity?: number;
+}
+
+export interface MoneyProps extends React.HTMLAttributes<HTMLElement> {
+  /** 必传：金额对象 */
+  data: MoneyData;
+  /** 不显示货币符号，只显示数字 */
+  withoutCurrency?: boolean;
+  /** 整数时不显示 .00 */
+  withoutTrailingZeros?: boolean;
+  /** locale 字符串（zh-CN / en-US / ...）。默认按 currencyCode 推断 */
+  locale?: string;
+  /** 渲染元素，默认 span */
+  as?: keyof JSX.IntrinsicElements;
+  /** unit price：渲染 ¥99.00/100g */
+  measurement?: MoneyMeasurement;
+}
+
+// currencyCode → 默认 locale 推断
+const DEFAULT_LOCALE_BY_CURRENCY: Record<string, string> = {
+  CNY: 'zh-CN',
+  USD: 'en-US',
+  EUR: 'de-DE',
+  GBP: 'en-GB',
+  JPY: 'ja-JP',
+  KRW: 'ko-KR',
+};
+
+export function Money(props: MoneyProps) {
+  const {
+    data,
+    withoutCurrency,
+    withoutTrailingZeros,
+    locale: localeProp,
+    as,
+    measurement,
+    ...rest
+  } = props;
+
+  const Tag: any = as || 'span';
+  const locale = localeProp || DEFAULT_LOCALE_BY_CURRENCY[data.currencyCode] || 'en-US';
+  const amount = Number(data.amount);
+
+  let formatted: string;
+  try {
+    const opts: Intl.NumberFormatOptions = withoutCurrency
+      ? {
+          minimumFractionDigits: withoutTrailingZeros && Number.isInteger(amount) ? 0 : 2,
+          maximumFractionDigits: 2,
+        }
+      : {
+          style: 'currency',
+          currency: data.currencyCode,
+          minimumFractionDigits: withoutTrailingZeros && Number.isInteger(amount) ? 0 : 2,
+          maximumFractionDigits: 2,
+        };
+    formatted = new Intl.NumberFormat(locale, opts).format(amount);
+  } catch {
+    // Fallback：Intl 不支持的 currencyCode
+    formatted = withoutCurrency ? amount.toFixed(2) : `${data.currencyCode} ${amount.toFixed(2)}`;
+  }
+
+  // measurement suffix（unit price）
+  let suffix = '';
+  if (measurement) {
+    const q = measurement.quantity ?? 1;
+    if (q === 1) {
+      suffix = `/${measurement.referenceUnit}`;
+    } else {
+      suffix = `/${q}${measurement.referenceUnit}`;
+    }
+  }
+
+  return (
+    <Tag {...rest} data-money={data.amount} data-money-currency={data.currencyCode}>
+      {formatted}
+      {suffix}
+    </Tag>
+  );
+}

package/src/components/ProductPrice.tsx

@@ -0,0 +1,61 @@
+/**
+ * <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 { Money, 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 function ProductPrice(props: ProductPriceProps) {
+  const {
+    price,
+    compareAtPrice,
+    measurement,
+    locale,
+    compareAtClassName,
+    as,
+    ...rest
+  } = props;
+
+  const Tag: any = as || 'div';
+  const hasDiscount =
+    compareAtPrice &&
+    Number(compareAtPrice.amount) > Number(price.amount);
+
+  return (
+    <Tag {...rest} data-product-price>
+      <Money data={price} locale={locale} measurement={measurement} />
+      {hasDiscount && compareAtPrice && (
+        <Money
+          data={compareAtPrice}
+          locale={locale}
+          as="s"
+          className={compareAtClassName}
+          data-compare-at="true"
+          style={{ marginLeft: '0.5em', opacity: 0.6 }}
+        />
+      )}
+    </Tag>
+  );
+}