@shopbb/helium 0.2.0 → 0.3.0-alpha.2

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,112 @@
+/**
+ * <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';
+import { useShopOptional } from './ShopProvider';
+
+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 shop = useShopOptional();
+  const locale =
+    localeProp ||
+    shop?.locale ||
+    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/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/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/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/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>
+      ))}
+    </>
+  );
+}