@shopbb/helium 0.5.10 → 0.6.1

package/src/components/Pagination.tsx

@@ -0,0 +1,139 @@
+/**
+ * <Pagination> + getPaginationVariables() — 对齐 Hydrogen Pagination
+ *
+ * GraphQL cursor-based 分页（forward + backward）。SSR 友好：URL ?cursor= / ?direction= 控制。
+ *
+ * 用法（服务端 loader）：
+ *
+ *   const variables = getPaginationVariables(request, { pageBy: 20 });
+ *   // → { first: 20, last: undefined, startCursor: undefined, endCursor: undefined }
+ *   const data = await storefront.query(PRODUCTS_QUERY, { variables });
+ *
+ * 用法（组件）：
+ *
+ *   <Pagination connection={data.products}>
+ *     {({ nodes, hasNextPage, NextLink, hasPreviousPage, PreviousLink, state }) => (
+ *       <>
+ *         {hasPreviousPage && <PreviousLink>上一页</PreviousLink>}
+ *         <ul>{nodes.map((n) => <li key={n.id}>{n.title}</li>)}</ul>
+ *         {hasNextPage && <NextLink>下一页</NextLink>}
+ *       </>
+ *     )}
+ *   </Pagination>
+ */
+
+import * as React from 'react';
+import { flattenConnection, type Connection } from '../utils/flattenConnection';
+
+const DEFAULT_PAGE_BY = 20;
+
+export interface PaginationConnection<T = any> {
+  pageInfo: {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor?: string | null;
+    endCursor?: string | null;
+  };
+  nodes?: T[];
+  edges?: Array<{ node: T; cursor?: string }>;
+}
+
+export interface PaginationVariables {
+  first?: number;
+  last?: number;
+  startCursor?: string | null;
+  endCursor?: string | null;
+}
+
+/**
+ * 从 request URL 解析分页 query params。
+ *
+ *   ?direction=next&cursor=xxx → { first: 20, endCursor: 'xxx' }
+ *   ?direction=previous&cursor=xxx → { last: 20, startCursor: 'xxx' }
+ *   (没 param) → { first: 20 }
+ */
+export function getPaginationVariables(
+  request: Request,
+  options: { pageBy?: number } = {},
+): PaginationVariables {
+  const { pageBy = DEFAULT_PAGE_BY } = options;
+  const url = new URL(request.url);
+  const direction = url.searchParams.get('direction');
+  const cursor = url.searchParams.get('cursor');
+  if (direction === 'previous' && cursor) {
+    return { last: pageBy, startCursor: cursor };
+  }
+  if (direction === 'next' && cursor) {
+    return { first: pageBy, endCursor: cursor };
+  }
+  return { first: pageBy };
+}
+
+export interface PaginationRenderProps<T> {
+  /** 拍平后的当前页 nodes */
+  nodes: T[];
+  /** Raw pageInfo（hasNextPage / hasPreviousPage 等） */
+  pageInfo: PaginationConnection['pageInfo'];
+  /** 当前 URL state */
+  state: { direction: 'next' | 'previous' | null; cursor: string | null };
+
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+  /** "下一页" 链接组件（自动加 ?direction=next&cursor=...） */
+  NextLink: React.FC<{ children: React.ReactNode; className?: string }>;
+  /** "上一页" 链接组件 */
+  PreviousLink: React.FC<{ children: React.ReactNode; className?: string }>;
+}
+
+export interface PaginationProps<T> {
+  connection: PaginationConnection<T>;
+  children: (props: PaginationRenderProps<T>) => React.ReactNode;
+}
+
+export function Pagination<T>(props: PaginationProps<T>) {
+  const { connection, children } = props;
+  const pageInfo = connection.pageInfo;
+  const nodes = flattenConnection(connection as Connection<T>);
+
+  // 当前 URL state（hydrate 后才能访问 window.location）
+  const [urlState, setUrlState] = React.useState<{ direction: 'next' | 'previous' | null; cursor: string | null }>({
+    direction: null, cursor: null,
+  });
+  React.useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const params = new URLSearchParams(window.location.search);
+    const d = params.get('direction');
+    setUrlState({
+      direction: d === 'next' || d === 'previous' ? d : null,
+      cursor: params.get('cursor'),
+    });
+  }, []);
+
+  const nextHref = pageInfo.endCursor
+    ? `?direction=next&cursor=${encodeURIComponent(pageInfo.endCursor)}`
+    : '#';
+  const prevHref = pageInfo.startCursor
+    ? `?direction=previous&cursor=${encodeURIComponent(pageInfo.startCursor)}`
+    : '#';
+
+  const NextLink: React.FC<{ children: React.ReactNode; className?: string }> = ({ children, className }) => (
+    <a href={nextHref} className={className} data-pagination-next>{children}</a>
+  );
+  const PreviousLink: React.FC<{ children: React.ReactNode; className?: string }> = ({ children, className }) => (
+    <a href={prevHref} className={className} data-pagination-prev>{children}</a>
+  );
+
+  return (
+    <>
+      {children({
+        nodes,
+        pageInfo,
+        state: urlState,
+        hasNextPage: pageInfo.hasNextPage,
+        hasPreviousPage: pageInfo.hasPreviousPage,
+        NextLink,
+        PreviousLink,
+      })}
+    </>
+  );
+}

package/src/components/RichText.tsx

@@ -0,0 +1,122 @@
+/**
+ * <RichText> — 对齐 Hydrogen React
+ *
+ * 渲染 Shopify rich-text metafield 的 JSON 结构。Shopify rich-text 标准格式：
+ *
+ *   {
+ *     type: "root",
+ *     children: [
+ *       { type: "heading", level: 1, children: [{type: "text", value: "Hello"}] },
+ *       { type: "paragraph", children: [
+ *         {type: "text", value: "Hello "},
+ *         {type: "text", value: "world", bold: true},
+ *         {type: "link", url: "...", children: [{type: "text", value: "click"}]},
+ *       ]},
+ *     ],
+ *   }
+ *
+ * 用法：
+ *   const rich = JSON.parse(product.descriptionRichText);
+ *   <RichText data={rich} />
+ *
+ *   // 自定义节点渲染（覆盖默认）
+ *   <RichText data={rich} components={{ heading: ({level, children}) =>
+ *     React.createElement(`h${level}`, {className: 'my-h'}, children) }} />
+ */
+
+import * as React from 'react';
+
+export interface RichTextNode {
+  type: string;
+  value?: string;
+  level?: number;
+  url?: string;
+  title?: string;
+  target?: string;
+  bold?: boolean;
+  italic?: boolean;
+  listType?: 'ordered' | 'unordered';
+  children?: RichTextNode[];
+}
+
+export interface RichTextComponents {
+  root?: (props: { children: React.ReactNode }) => React.ReactElement;
+  paragraph?: (props: { children: React.ReactNode }) => React.ReactElement;
+  heading?: (props: { level: number; children: React.ReactNode }) => React.ReactElement;
+  list?: (props: { listType: 'ordered' | 'unordered'; children: React.ReactNode }) => React.ReactElement;
+  listItem?: (props: { children: React.ReactNode }) => React.ReactElement;
+  link?: (props: { url: string; title?: string; target?: string; children: React.ReactNode }) => React.ReactElement;
+  text?: (props: { value: string; bold?: boolean; italic?: boolean }) => React.ReactElement;
+}
+
+export interface RichTextProps {
+  /** Rich-text JSON object（已 parse 过的）或者 JSON string */
+  data: RichTextNode | string | null | undefined;
+  /** 自定义渲染器 */
+  components?: RichTextComponents;
+  /** 包裹容器 className */
+  className?: string;
+}
+
+const DEFAULTS: Required<RichTextComponents> = {
+  root: ({ children }) => <div data-rich-text>{children}</div>,
+  paragraph: ({ children }) => <p>{children}</p>,
+  heading: ({ level, children }) => React.createElement(`h${Math.min(Math.max(level, 1), 6)}`, null, children),
+  list: ({ listType, children }) => (listType === 'ordered' ? <ol>{children}</ol> : <ul>{children}</ul>),
+  listItem: ({ children }) => <li>{children}</li>,
+  link: ({ url, title, target, children }) => (
+    <a href={url} title={title} target={target} rel={target === '_blank' ? 'noopener noreferrer' : undefined}>
+      {children}
+    </a>
+  ),
+  text: ({ value, bold, italic }) => {
+    let out: React.ReactNode = value;
+    if (italic) out = <em>{out}</em>;
+    if (bold) out = <strong>{out}</strong>;
+    return <>{out}</>;
+  },
+};
+
+function renderNode(node: RichTextNode, comps: Required<RichTextComponents>, key: number | string): React.ReactNode {
+  if (!node) return null;
+  const childrenNodes = (node.children || []).map((c, i) => renderNode(c, comps, i));
+  switch (node.type) {
+    case 'root':
+      return <React.Fragment key={key}>{comps.root({ children: childrenNodes })}</React.Fragment>;
+    case 'paragraph':
+      return <React.Fragment key={key}>{comps.paragraph({ children: childrenNodes })}</React.Fragment>;
+    case 'heading':
+      return <React.Fragment key={key}>{comps.heading({ level: node.level || 2, children: childrenNodes })}</React.Fragment>;
+    case 'list':
+      return <React.Fragment key={key}>{comps.list({ listType: node.listType || 'unordered', children: childrenNodes })}</React.Fragment>;
+    case 'list-item':
+      return <React.Fragment key={key}>{comps.listItem({ children: childrenNodes })}</React.Fragment>;
+    case 'link':
+      return <React.Fragment key={key}>{comps.link({ url: node.url || '#', title: node.title, target: node.target, children: childrenNodes })}</React.Fragment>;
+    case 'text':
+      return <React.Fragment key={key}>{comps.text({ value: node.value || '', bold: node.bold, italic: node.italic })}</React.Fragment>;
+    default:
+      // unknown type — 递归 children 不出错
+      return <React.Fragment key={key}>{childrenNodes}</React.Fragment>;
+  }
+}
+
+export function RichText({ data, components, className }: RichTextProps) {
+  let parsed: RichTextNode | null = null;
+  if (!data) return null;
+  if (typeof data === 'string') {
+    try { parsed = JSON.parse(data); } catch { return <div className={className}>{data}</div>; }
+  } else {
+    parsed = data;
+  }
+  if (!parsed) return null;
+
+  const comps: Required<RichTextComponents> = { ...DEFAULTS, ...(components || {}) };
+  const rendered = renderNode(parsed, comps, 0);
+
+  if (className && parsed.type === 'root') {
+    // 简单包一层，给 root 加 className
+    return <div className={className} data-rich-text>{rendered}</div>;
+  }
+  return <>{rendered}</>;
+}

package/src/components/Seo.tsx

@@ -0,0 +1,61 @@
+/**
+ * <Seo data={SeoConfig} /> — 对齐 Hydrogen React
+ *
+ * Hydrogen 在 Remix 里用 `meta` export 注入 head；我们在客户端用 `<Seo>`
+ * 做 SPA 路由切换时的 document.title / meta 动态更新。
+ *
+ * SSR 阶段 Seo 组件渲染为 null（不输出 DOM）；服务端商家应该用 getSeoMeta
+ * 生成 head HTML 直接拼到 <head>。
+ *
+ * 用法（客户端 SPA navigate 时）：
+ *
+ *   <Seo data={{
+ *     title: product.title,
+ *     description: product.description,
+ *     image: product.featuredImage?.url,
+ *     url: location.href,
+ *     type: 'product',
+ *   }} />
+ */
+
+import * as React from 'react';
+import { getSeoMeta, type SeoConfig } from '../seo/getSeoMeta';
+
+export interface SeoProps {
+  data: SeoConfig;
+}
+
+export function Seo({ data }: SeoProps) {
+  React.useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const seo = getSeoMeta(data);
+
+    if (seo.fullTitle) document.title = seo.fullTitle;
+
+    // 同步关键 meta：description / og:* / twitter:*
+    for (const m of seo.meta) {
+      const attr = m.name ? 'name' : 'property';
+      const key = m.name || m.property!;
+      let el = document.querySelector(`meta[${attr}="${key}"]`) as HTMLMetaElement | null;
+      if (!el) {
+        el = document.createElement('meta');
+        el.setAttribute(attr, key);
+        document.head.appendChild(el);
+      }
+      el.setAttribute('content', m.content);
+    }
+
+    // canonical
+    if (data.url) {
+      let canon = document.querySelector('link[rel="canonical"]') as HTMLLinkElement | null;
+      if (!canon) {
+        canon = document.createElement('link');
+        canon.setAttribute('rel', 'canonical');
+        document.head.appendChild(canon);
+      }
+      canon.setAttribute('href', data.url);
+    }
+  }, [data]);
+
+  return null;
+}

package/src/components/hooks/useMoney.ts

@@ -0,0 +1,87 @@
+/**
+ * useMoney — 对齐 Hydrogen React 同名 hook
+ *
+ * 把 GraphQL MoneyV2 拆成多个易用字段，便于自定义渲染。
+ *
+ *   const { amount, currencyCode, currencySymbol, withoutTrailingZerosAndCurrency }
+ *     = useMoney({amount: '99.00', currencyCode: 'CNY'});
+ *
+ *   <div>
+ *     <span>{currencySymbol}</span>
+ *     <strong>{withoutTrailingZerosAndCurrency}</strong>
+ *   </div>
+ *
+ * 与 <Money> 组件的关系：<Money> 是默认渲染；useMoney() 是低层 API，给商家
+ * 自定义结构用。两者背后用同一份 currency symbol 表 + 格式化逻辑。
+ */
+
+import * as React from 'react';
+
+export interface MoneyV2 {
+  amount: string;
+  currencyCode: string;
+}
+
+export interface MoneyParts {
+  /** 标准化后的金额字符串："99.00" → "99.00"（保留两位） */
+  amount: string;
+  /** 货币代码："CNY" */
+  currencyCode: string;
+  /** 货币符号："¥" */
+  currencySymbol: string;
+  /** 带符号 + 千分位："¥99.00" */
+  localizedString: string;
+  /** 去掉尾零："99.00" → "99"；"99.50" 不变 */
+  withoutTrailingZeros: string;
+  /** 去掉尾零 + 货币符号："99" / "1,250" */
+  withoutTrailingZerosAndCurrency: string;
+  /** 仅货币符号 + 金额，不带千分位（用于排版极简场景）："¥99" */
+  symbolWithoutTrailingZeros: string;
+  /** 千分位金额："1,234.56" */
+  amountWithComma: string;
+}
+
+const CURRENCY_SYMBOL: Record<string, string> = {
+  CNY: '¥', USD: '$', EUR: '€', GBP: '£', JPY: '¥', HKD: 'HK$', KRW: '₩',
+  AUD: 'A$', CAD: 'CA$', SGD: 'S$', TWD: 'NT$', INR: '₹', BRL: 'R$',
+};
+
+function formatAmount(num: number, minDec: number, maxDec: number): string {
+  if (!Number.isFinite(num)) return '0';
+  const neg = num < 0;
+  const abs = Math.abs(num);
+  const fixed = abs.toFixed(maxDec);
+  const [intPart, decPart = ''] = fixed.split('.');
+  const intWithSep = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  let trimDec = decPart;
+  while (trimDec.length > minDec && trimDec.endsWith('0')) {
+    trimDec = trimDec.slice(0, -1);
+  }
+  const out = trimDec ? `${intWithSep}.${trimDec}` : intWithSep;
+  return neg ? `-${out}` : out;
+}
+
+export function useMoney(money: MoneyV2 | null | undefined): MoneyParts {
+  return React.useMemo<MoneyParts>(() => {
+    const amount = money?.amount ?? '0';
+    const currencyCode = money?.currencyCode ?? 'USD';
+    const num = Number(amount);
+    const symbol = CURRENCY_SYMBOL[currencyCode] ?? currencyCode + ' ';
+
+    const amountWithComma = formatAmount(num, 2, 2);
+    const withoutTrailingZeros = formatAmount(num, 0, 2);
+    const localizedString = `${symbol}${amountWithComma}`;
+    const withoutTrailingZerosAndCurrency = withoutTrailingZeros;
+    const symbolWithoutTrailingZeros = `${symbol}${withoutTrailingZeros}`;
+    return {
+      amount: num.toFixed(2),
+      currencyCode,
+      currencySymbol: symbol,
+      localizedString,
+      withoutTrailingZeros,
+      withoutTrailingZerosAndCurrency,
+      symbolWithoutTrailingZeros,
+      amountWithComma,
+    };
+  }, [money?.amount, money?.currencyCode]);
+}

package/src/components/hooks/useOptimisticCart.ts

@@ -0,0 +1,183 @@
+/**
+ * useOptimisticCart — 对齐 Hydrogen React 同名 hook
+ *
+ * 接受 actualCart（来自 CartProvider），返回一个"叠加了所有 pending mutation"
+ * 的 cart 视图。让 UI 在网络回来之前立刻反应用户操作（数量+1 / 删除等）。
+ *
+ *   const { cart: actualCart } = useCart();
+ *   const cart = useOptimisticCart(actualCart);
+ *   // cart 看起来已经"立刻应用了"，但 fetcher 还在跑后端
+ *
+ * 实现：
+ *   - <CartForm> submit 时把 pending action 注册到模块内 store
+ *   - 完成后从 store 摘掉
+ *   - useOptimisticCart 订阅 store，把 actualCart 复制一份 + 应用所有 pending
+ *
+ * 简化点（vs Hydrogen 完整实现）：
+ *   - 只支持 LinesAdd / LinesUpdate / LinesRemove（足够 cart 主流操作）
+ *   - DiscountCodesUpdate / NoteUpdate 等不做 optimistic（这些在网络层用 applyCart 兜底）
+ *   - 不持久化（页面刷新清空）
+ */
+
+import * as React from 'react';
+import { useCartOptional } from '../CartProvider';
+
+// ============================================================
+// Pending mutation store（模块级单例）
+// ============================================================
+
+export interface PendingMutation {
+  id: string;  // unique
+  action: 'LinesAdd' | 'LinesUpdate' | 'LinesRemove';
+  inputs: any;
+}
+
+// 关键：snapshot 必须是稳定引用，否则 useSyncExternalStore 每次比对都觉得变了 →
+// 无限 re-render（React #185）+ hydration mismatch（#418/#423）
+const EMPTY_SNAPSHOT: PendingMutation[] = [];
+
+const pendingStore = {
+  items: new Map<string, PendingMutation>(),
+  listeners: new Set<() => void>(),
+  cachedSnapshot: EMPTY_SNAPSHOT as PendingMutation[],
+
+  add(m: PendingMutation) {
+    this.items.set(m.id, m);
+    this.cachedSnapshot = Array.from(this.items.values());
+    this.notify();
+  },
+  remove(id: string) {
+    if (this.items.delete(id)) {
+      this.cachedSnapshot = this.items.size === 0 ? EMPTY_SNAPSHOT : Array.from(this.items.values());
+      this.notify();
+    }
+  },
+  list(): PendingMutation[] {
+    // 返回稳定引用（只在 add/remove 时改变）— 满足 useSyncExternalStore 契约
+    return this.cachedSnapshot;
+  },
+  subscribe(fn: () => void): () => void {
+    this.listeners.add(fn);
+    return () => { this.listeners.delete(fn); };
+  },
+  notify() {
+    for (const fn of this.listeners) fn();
+  },
+};
+
+/**
+ * Internal: CartForm 提交时调用，注册一个 pending mutation。返回 unregister。
+ */
+export function __registerPendingMutation(m: PendingMutation): () => void {
+  pendingStore.add(m);
+  return () => pendingStore.remove(m.id);
+}
+
+// ============================================================
+// useOptimisticCart hook
+// ============================================================
+
+export interface OptimisticCartLine {
+  id: string;
+  quantity: number;
+  isOptimistic?: boolean;
+  merchandise?: any;
+  cost?: any;
+  attributes?: any;
+  [key: string]: any;
+}
+
+export interface OptimisticCart<TCart = any> {
+  isOptimistic?: boolean;
+  totalQuantity?: number;
+  lines?: { nodes: OptimisticCartLine[]; edges?: any };
+  cost?: any;
+  [key: string]: any;
+}
+
+export function useOptimisticCart<TCart extends OptimisticCart = OptimisticCart>(
+  actualCart: TCart | null,
+): TCart | null {
+  // 订阅 pending store 重渲染
+  const subscribe = React.useCallback((cb: () => void) => pendingStore.subscribe(cb), []);
+  const getSnapshot = React.useCallback(() => pendingStore.list(), []);
+  const pendings = React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  // 如果没有 pending，CartProvider 内部的 cart 已经是最新（因为 applyCart 同步过）
+  const fallback = useCartOptional();
+  const baseCart = (actualCart ?? (fallback?.cart as any)) as TCart | null;
+
+  return React.useMemo(() => {
+    if (!baseCart) {
+      // 如果没有 actual cart 但有 pending LinesAdd → 模拟一个空 cart + 即将添加的行
+      if (pendings.length === 0) return null;
+      const optimisticLines: OptimisticCartLine[] = [];
+      for (const p of pendings) {
+        if (p.action === 'LinesAdd' && Array.isArray(p.inputs?.lines)) {
+          for (const ln of p.inputs.lines) {
+            optimisticLines.push({
+              id: `__optimistic_${p.id}_${ln.merchandiseId}`,
+              quantity: ln.quantity ?? 1,
+              merchandise: { id: ln.merchandiseId },
+              isOptimistic: true,
+            });
+          }
+        }
+      }
+      if (optimisticLines.length === 0) return null;
+      return {
+        isOptimistic: true,
+        totalQuantity: optimisticLines.reduce((s, l) => s + l.quantity, 0),
+        lines: { nodes: optimisticLines },
+      } as TCart;
+    }
+
+    if (pendings.length === 0) return baseCart;
+
+    // 复制 lines（不深拷贝整个 cart — 只动 lines 节点列表）
+    const linesNodes = ((baseCart as any).lines?.nodes ?? []).slice() as OptimisticCartLine[];
+
+    for (const p of pendings) {
+      if (p.action === 'LinesAdd' && Array.isArray(p.inputs?.lines)) {
+        for (const ln of p.inputs.lines) {
+          // 简化：若已有相同 merchandiseId 累加，否则追加
+          const idx = linesNodes.findIndex((l) => l.merchandise?.id === ln.merchandiseId);
+          if (idx >= 0) {
+            linesNodes[idx] = {
+              ...linesNodes[idx],
+              quantity: linesNodes[idx].quantity + (ln.quantity ?? 1),
+              isOptimistic: true,
+            };
+          } else {
+            linesNodes.push({
+              id: `__optimistic_${p.id}_${ln.merchandiseId}`,
+              quantity: ln.quantity ?? 1,
+              merchandise: { id: ln.merchandiseId },
+              isOptimistic: true,
+            });
+          }
+        }
+      } else if (p.action === 'LinesUpdate' && Array.isArray(p.inputs?.lines)) {
+        for (const ln of p.inputs.lines) {
+          const idx = linesNodes.findIndex((l) => l.id === ln.id);
+          if (idx >= 0) {
+            linesNodes[idx] = { ...linesNodes[idx], quantity: ln.quantity ?? linesNodes[idx].quantity, isOptimistic: true };
+          }
+        }
+      } else if (p.action === 'LinesRemove' && Array.isArray(p.inputs?.lineIds)) {
+        for (const id of p.inputs.lineIds) {
+          const idx = linesNodes.findIndex((l) => l.id === id);
+          if (idx >= 0) linesNodes.splice(idx, 1);
+        }
+      }
+    }
+
+    const totalQuantity = linesNodes.reduce((s, l) => s + l.quantity, 0);
+    return {
+      ...(baseCart as any),
+      isOptimistic: true,
+      totalQuantity,
+      lines: { ...(baseCart as any).lines, nodes: linesNodes },
+    } as TCart;
+  }, [baseCart, pendings]);
+}

package/src/components/index.ts

@@ -22,6 +22,9 @@
 // Providers + hooks
 export { ShopProvider, useShop, useShopOptional } from './ShopProvider';
 export type { ShopContextValue, ShopProviderProps } from './ShopProvider';
+// Hydrogen-compatible alias: <ShopifyProvider> 在我们叫 <ShopProvider>，提供别名让 Hydrogen 代码无痛迁移
+export { ShopProvider as ShopifyProvider } from './ShopProvider';
+export type { ShopProviderProps as ShopifyProviderProps } from './ShopProvider';
 
 export { CartProvider, useCart, useCartOptional } from './CartProvider';
 export type {
@@ -133,3 +136,44 @@ export type { DiscountSelectorProps } from './DiscountSelector';
 
 // SSR / hydrate 辅助 hook
 export { useMounted } from './hooks/useMounted';
+export { useOptimisticCart } from './hooks/useOptimisticCart';
+export type { OptimisticCart, OptimisticCartLine, PendingMutation } from './hooks/useOptimisticCart';
+export { useMoney } from './hooks/useMoney';
+export type { MoneyV2, MoneyParts } from './hooks/useMoney';
+
+// CartForm — Hydrogen-compatible form-based cart mutation API
+export { CartForm, CART_FORM_ACTIONS, useFetcher } from './CartForm';
+export type {
+  CartFormProps, CartFormInput, CartFormFetcher, CartFormAction,
+  CartLineInput, CartLineUpdateInput,
+} from './CartForm';
+
+// Cart line context + 子组件
+export { CartLineProvider, useCartLine, useCartLineOptional } from './CartLineProvider';
+export type { CartLineProviderProps, CartLineLike } from './CartLineProvider';
+export { CartLineQuantity } from './CartLineQuantity';
+export type { CartLineQuantityProps } from './CartLineQuantity';
+export { CartCost } from './CartCost';
+export type { CartCostProps, MoneyValue } from './CartCost';
+export { CartCheckoutButton } from './CartCheckoutButton';
+export type { CartCheckoutButtonProps } from './CartCheckoutButton';
+export { BuyNowButton } from './BuyNowButton';
+export type { BuyNowButtonProps } from './BuyNowButton';
+
+// Rich text
+export { RichText } from './RichText';
+export type { RichTextProps, RichTextNode, RichTextComponents } from './RichText';
+
+// Pagination
+export { Pagination, getPaginationVariables } from './Pagination';
+export type { PaginationProps, PaginationConnection, PaginationRenderProps, PaginationVariables } from './Pagination';
+
+// SEO
+export { Seo } from './Seo';
+export type { SeoProps } from './Seo';
+
+// 通用工具
+export { flattenConnection } from '../utils/flattenConnection';
+export type { Connection } from '../utils/flattenConnection';
+export { parseGid } from '../utils/parseGid';
+export type { ParsedGid } from '../utils/parseGid';