@shopbb/helium 0.1.0 → 0.3.0-alpha.1

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>
+  );
+}

package/src/components/VariantSelector.tsx

@@ -0,0 +1,148 @@
+/**
+ * <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 function VariantSelector(props: VariantSelectorProps) {
+  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: VariantOption[] = 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<string, Set<string>>();
+    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: string, optionValue: string) => {
+    const currentSelected = new Map<string, string>(
+      (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 (
+    <>
+      {options.map((option) => (
+        <React.Fragment key={option.name}>
+          {children({
+            option,
+            value: currentVariant?.selectedOptions?.find((so) => so.name === option.name)?.value,
+            onSelect: (val) => handleSelect(option.name, val),
+          })}
+        </React.Fragment>
+      ))}
+    </>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @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';