@shopbb/helium 0.7.7 → 0.9.0

package/src/analytics/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Analytics SDK 类型
+ *
+ * Helium 的埋点接口。与 platform-api 的事件 schema 保持一致。
+ */
+
+export type EventType =
+  | 'page_view'
+  | 'product_view'
+  | 'add_to_cart'
+  | 'checkout_start'
+  | 'checkout_paid';
+
+/** 单条事件输入 */
+export interface AnalyticsEvent {
+  /** 事件类型 */
+  type: EventType;
+  /** 客户端发生时间（秒，Unix）。默认 Date.now()/1000 */
+  occurredAt?: number;
+  /** 页面 path（默认 window.location.pathname） */
+  path?: string;
+  /** referrer（默认 document.referrer） */
+  referrer?: string;
+  /** 事件附加数据 */
+  props?: Record<string, unknown>;
+}
+
+/** 各事件的 props 形状 */
+export interface PageViewProps {
+  title?: string;
+}
+
+export interface ProductViewProps {
+  productId: string;
+  variantId?: string;
+  priceCents?: number;
+  currency?: string;
+}
+
+export interface AddToCartProps {
+  productId: string;
+  variantId?: string;
+  quantity: number;
+  priceCents?: number;
+  currency?: string;
+}
+
+export interface CheckoutStartProps {
+  cartId?: string;
+  itemCount: number;
+  subtotalCents: number;
+  currency: string;
+}
+
+/** AnalyticsProvider 初始化配置 */
+export interface AnalyticsConfig {
+  /** 平台 API base URL，例如 https://api.oxygen-demo.cloudc.top */
+  apiBase: string;
+  /** Storefront public access token */
+  publicAccessToken: string;
+  /** 当前买家 ID（已登录时传入） */
+  buyerId?: string | null;
+  /** 是否开启 debug 日志 */
+  debug?: boolean;
+  /** flush 间隔（毫秒），默认 3000 */
+  flushIntervalMs?: number;
+  /** 批量上限（条），默认 20 */
+  flushBatchSize?: number;
+}
+
+/** track 函数签名 */
+export type TrackFn = (event: AnalyticsEvent) => void;
+
+/** 内部队列条目 */
+export interface QueuedEvent {
+  type: EventType;
+  occurredAt: number;
+  path: string | null;
+  referrer: string | null;
+  props: Record<string, unknown>;
+}

package/src/components/AddToCartButton.tsx

@@ -39,6 +39,12 @@ export interface AddToCartButtonProps {
   route?: string;
   /** 按钮 children */
   children?: React.ReactNode;
+  /**
+   * 按钮被点击时触发（form 提交之前）。
+   * 用于埋点 / dataLayer / 自定义分析回调。
+   * 不影响表单提交流程。
+   */
+  onAdd?: (line: CartLineInput) => void;
 }
 
 export function AddToCartButton(props: AddToCartButtonProps) {
@@ -53,6 +59,7 @@ export function AddToCartButton(props: AddToCartButtonProps) {
     className,
     route = '/cart',
     children = '加入购物车',
+    onAdd,
   } = props;
 
   const line: CartLineInput = { merchandiseId: variantId, quantity };
@@ -74,6 +81,17 @@ export function AddToCartButton(props: AddToCartButtonProps) {
             disabled={disabled || submitting}
             data-add-to-cart
             data-loading={submitting ? '' : undefined}
+            onClick={() => {
+              if (onAdd && !submitting && !disabled) {
+                try {
+                  onAdd(line);
+                } catch (err) {
+                  if (typeof console !== 'undefined') {
+                    console.warn('[AddToCartButton] onAdd threw', err);
+                  }
+                }
+              }
+            }}
           >
             {submitting ? loadingText : disabled ? unavailableText : children}
           </button>

package/src/page-schema/PageRenderer.tsx

@@ -0,0 +1,147 @@
+/**
+ * <PageRenderer> — 按 Page Schema 渲染一整页
+ *
+ * 同一份组件在 production storefront 与 admin 编辑器画布共用。
+ *
+ * 商品网格的 selection_mode 自动模式（newest / top-selling / collection）
+ * 由父组件预先拉数据通过 productsBySection prop 注入，组件本身不发请求。
+ * 这让 renderer 保持纯组件、可在 SSR / CSR / 编辑器画布任何环境用。
+ */
+
+import * as React from 'react';
+import type { AnySection, Page } from './types';
+import { HeroSection } from './sections/Hero';
+import { ProductGridSection } from './sections/ProductGrid';
+import { BannerSection } from './sections/Banner';
+import { RichTextSection } from './sections/RichText';
+import { ImageSection } from './sections/Image';
+import { SpacerSection } from './sections/Spacer';
+
+export interface PageRendererProps {
+  page: Page;
+  /**
+   * 按 section.id 提供该 section 用到的商品数据（仅 product-grid 用到）。
+   * Page renderer 不发请求，请父组件按 schema 计算后传入。
+   */
+  productsBySection?: Record<string, any[]>;
+  /**
+   * 编辑器模式下传入 onSectionClick / selectedSectionId，渲染时会给每个 section
+   * 加 hover / 选中外框，便于点选定位。
+   */
+  editorMode?: {
+    selectedSectionId?: string | null;
+    onSectionClick?: (sectionId: string) => void;
+  };
+}
+
+export function PageRenderer({
+  page,
+  productsBySection,
+  editorMode,
+}: PageRendererProps): React.ReactElement {
+  const globalStyle: React.CSSProperties = {
+    backgroundColor: page.global_style?.background_color,
+    color: '#0f172a',
+    fontFamily:
+      page.global_style?.font_family === 'serif'
+        ? 'Georgia, "Times New Roman", serif'
+        : page.global_style?.font_family === 'sans-serif'
+          ? '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
+          : 'inherit',
+  };
+
+  return (
+    <div style={globalStyle} data-page-slug={page.slug}>
+      {page.sections
+        .filter((s) => s.visible !== false)
+        .map((section) => (
+          <SectionFrame
+            key={section.id}
+            section={section}
+            productsBySection={productsBySection}
+            editorMode={editorMode}
+          />
+        ))}
+    </div>
+  );
+}
+
+interface SectionFrameProps {
+  section: AnySection;
+  productsBySection?: Record<string, any[]>;
+  editorMode?: PageRendererProps['editorMode'];
+}
+
+function SectionFrame({ section, productsBySection, editorMode }: SectionFrameProps): React.ReactElement {
+  const isSelected = editorMode?.selectedSectionId === section.id;
+  const isEditor = !!editorMode;
+
+  const handleClick = (e: React.MouseEvent) => {
+    if (!isEditor) return;
+    // 阻止内部 a 链接跳转，让商家专注于选中
+    e.preventDefault();
+    e.stopPropagation();
+    editorMode?.onSectionClick?.(section.id);
+  };
+
+  const editorStyle: React.CSSProperties = isEditor
+    ? {
+        position: 'relative',
+        cursor: 'pointer',
+        outline: isSelected ? '2px solid #f97316' : '2px solid transparent',
+        outlineOffset: '-2px',
+        transition: 'outline-color 120ms ease',
+      }
+    : {};
+
+  const onMouseEnter = (e: React.MouseEvent<HTMLDivElement>) => {
+    if (!isEditor || isSelected) return;
+    (e.currentTarget as HTMLDivElement).style.outlineColor = '#fed7aa';
+  };
+  const onMouseLeave = (e: React.MouseEvent<HTMLDivElement>) => {
+    if (!isEditor || isSelected) return;
+    (e.currentTarget as HTMLDivElement).style.outlineColor = 'transparent';
+  };
+
+  return (
+    <div
+      data-section-id={section.id}
+      data-section-type={section.type}
+      style={editorStyle}
+      onClick={handleClick}
+      onMouseEnter={onMouseEnter}
+      onMouseLeave={onMouseLeave}
+    >
+      {renderSection(section, productsBySection)}
+    </div>
+  );
+}
+
+function renderSection(section: AnySection, productsBySection?: Record<string, any[]>) {
+  switch (section.type) {
+    case 'hero':
+      return <HeroSection data={section.data} />;
+    case 'product-grid':
+      return (
+        <ProductGridSection
+          data={section.data}
+          products={productsBySection?.[section.id]}
+        />
+      );
+    case 'banner':
+      return <BannerSection data={section.data} />;
+    case 'rich-text':
+      return <RichTextSection data={section.data} />;
+    case 'image':
+      return <ImageSection data={section.data} />;
+    case 'spacer':
+      return <SpacerSection data={section.data} />;
+    default:
+      // exhaustive check
+      return (
+        <div style={{ padding: 16, background: '#fef2f2', color: '#b91c1c' }}>
+          未知 section 类型：{(section as any).type}
+        </div>
+      );
+  }
+}

package/src/page-schema/index.ts

@@ -0,0 +1,48 @@
+/**
+ * @shopbb/helium 的 Page Schema 模块
+ *
+ * 公开 API：
+ *   - types：Page / Section / 各 section 的 data 类型
+ *   - <PageRenderer>：按 schema 渲染一整页
+ *   - 6 个 section 组件（也可以单独引用）
+ *   - 工具：createSection / createEmptyPage / validatePage / DEFAULT_DATA
+ */
+
+export type {
+  Page,
+  PageGlobalStyle,
+  Section,
+  AnySection,
+  SectionType,
+  HeroData,
+  HeroSection as HeroSectionType,
+  ProductGridData,
+  ProductGridSection as ProductGridSectionType,
+  BannerData,
+  BannerSection as BannerSectionType,
+  RichTextData,
+  RichTextSection as RichTextSectionType,
+  ImageData,
+  ImageSection as ImageSectionType,
+  SpacerData,
+  SpacerSection as SpacerSectionType,
+} from './types';
+
+export {
+  newSectionId,
+  createSection,
+  createEmptyPage,
+  validateSection,
+  validatePage,
+  DEFAULT_DATA,
+} from './types';
+
+export { PageRenderer } from './PageRenderer';
+export type { PageRendererProps } from './PageRenderer';
+
+export { HeroSection } from './sections/Hero';
+export { ProductGridSection } from './sections/ProductGrid';
+export { BannerSection } from './sections/Banner';
+export { RichTextSection } from './sections/RichText';
+export { ImageSection } from './sections/Image';
+export { SpacerSection } from './sections/Spacer';

package/src/page-schema/sections/Banner.tsx

@@ -0,0 +1,63 @@
+/**
+ * <BannerSection> — 顶部细条状横幅
+ */
+
+import * as React from 'react';
+import type { BannerData } from '../types';
+
+export interface BannerSectionProps {
+  data: BannerData;
+}
+
+export function BannerSection({ data }: BannerSectionProps): React.ReactElement | null {
+  const [dismissed, setDismissed] = React.useState(false);
+  if (dismissed) return null;
+
+  const style: React.CSSProperties = {
+    padding: '12px 32px',
+    background: data.background_color ?? '#f97316',
+    color: data.text_color ?? '#ffffff',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 14,
+    fontSize: 14,
+    fontWeight: 500,
+  };
+
+  return (
+    <div style={style}>
+      <span>{data.text}</span>
+      {data.link && (
+        <a
+          href={data.link}
+          style={{
+            color: 'inherit',
+            textDecoration: 'underline',
+            fontWeight: 600,
+          }}
+        >
+          {data.link_label ?? '查看详情'}
+        </a>
+      )}
+      {data.dismissible && (
+        <button
+          type="button"
+          aria-label="关闭"
+          onClick={() => setDismissed(true)}
+          style={{
+            marginLeft: 'auto',
+            background: 'transparent',
+            border: 'none',
+            color: 'inherit',
+            cursor: 'pointer',
+            fontSize: 18,
+            opacity: 0.8,
+          }}
+        >
+          ×
+        </button>
+      )}
+    </div>
+  );
+}

package/src/page-schema/sections/Hero.tsx

@@ -0,0 +1,92 @@
+/**
+ * <HeroSection> — 渲染 hero 区块
+ *
+ * 这是按 Page Schema 设计的纯渲染组件：
+ *   - props 直接接收 HeroData
+ *   - 不读取 schema，不操作 schema，只渲染
+ *   - 编辑器与 production storefront 共用同一份组件
+ */
+
+import * as React from 'react';
+import type { HeroData } from '../types';
+
+export interface HeroSectionProps {
+  data: HeroData;
+}
+
+const HEIGHT_MAP: Record<NonNullable<HeroData['height']>, string> = {
+  small: '240px',
+  medium: '380px',
+  large: '540px',
+  full: '85vh',
+};
+
+export function HeroSection({ data }: HeroSectionProps): React.ReactElement {
+  const height = HEIGHT_MAP[data.height ?? 'medium'];
+  const align = data.text_align ?? 'center';
+
+  const style: React.CSSProperties = {
+    position: 'relative',
+    minHeight: height,
+    display: 'flex',
+    flexDirection: 'column',
+    justifyContent: 'center',
+    alignItems: align === 'center' ? 'center' : align === 'right' ? 'flex-end' : 'flex-start',
+    padding: '64px 32px',
+    background: data.background_image
+      ? `linear-gradient(rgba(0,0,0,0.35), rgba(0,0,0,0.35)), url(${data.background_image}) center/cover`
+      : data.background_color ?? '#0f172a',
+    color: data.text_color ?? '#ffffff',
+    textAlign: align,
+  };
+
+  return (
+    <section style={style}>
+      <h1 style={{ fontSize: 'clamp(2rem, 5vw, 3.5rem)', fontWeight: 800, margin: 0, maxWidth: '24ch' }}>
+        {data.headline}
+      </h1>
+      {data.subheadline && (
+        <p style={{ fontSize: 'clamp(1rem, 2vw, 1.25rem)', marginTop: 16, maxWidth: '40ch', opacity: 0.9 }}>
+          {data.subheadline}
+        </p>
+      )}
+      {(data.cta_label || data.secondary_cta_label) && (
+        <div style={{ marginTop: 28, display: 'flex', gap: 12, flexWrap: 'wrap', justifyContent: align }}>
+          {data.cta_label && (
+            <a
+              href={data.cta_link ?? '#'}
+              style={{
+                padding: '12px 28px',
+                background: data.text_color === '#ffffff' ? '#fff' : '#0f172a',
+                color: data.text_color === '#ffffff' ? '#0f172a' : '#ffffff',
+                borderRadius: 8,
+                fontWeight: 600,
+                textDecoration: 'none',
+                fontSize: 15,
+              }}
+            >
+              {data.cta_label}
+            </a>
+          )}
+          {data.secondary_cta_label && (
+            <a
+              href={data.secondary_cta_link ?? '#'}
+              style={{
+                padding: '12px 28px',
+                background: 'transparent',
+                color: 'inherit',
+                border: '1px solid currentColor',
+                borderRadius: 8,
+                fontWeight: 600,
+                textDecoration: 'none',
+                fontSize: 15,
+              }}
+            >
+              {data.secondary_cta_label}
+            </a>
+          )}
+        </div>
+      )}
+    </section>
+  );
+}

package/src/page-schema/sections/Image.tsx

@@ -0,0 +1,42 @@
+/**
+ * <ImageSection> — 单张图片，可加链接
+ */
+
+import * as React from 'react';
+import type { ImageData } from '../types';
+
+export interface ImageSectionProps {
+  data: ImageData;
+}
+
+const WIDTH_MAP: Record<NonNullable<ImageData['width']>, string> = {
+  full: '100%',
+  normal: '1200px',
+  narrow: '760px',
+};
+
+export function ImageSection({ data }: ImageSectionProps): React.ReactElement {
+  const maxWidth = WIDTH_MAP[data.width ?? 'normal'];
+
+  const img = (
+    <img
+      src={data.url}
+      alt={data.alt ?? ''}
+      style={{ display: 'block', width: '100%', height: 'auto' }}
+    />
+  );
+
+  return (
+    <section style={{ padding: data.width === 'full' ? 0 : '32px', textAlign: 'center' }}>
+      <div style={{ maxWidth, margin: '0 auto' }}>
+        {data.link ? (
+          <a href={data.link} style={{ display: 'block' }}>
+            {img}
+          </a>
+        ) : (
+          img
+        )}
+      </div>
+    </section>
+  );
+}

package/src/page-schema/sections/ProductGrid.tsx

@@ -0,0 +1,96 @@
+/**
+ * <ProductGridSection> — 商品网格
+ *
+ * 拉取商品数据需要 storefront client，由父组件通过 props 注入避免组件耦合。
+ *
+ * P0 简化：组件本身不拉数据，仅按传入的 products 数组渲染。Page renderer 负责
+ * 在渲染前根据 selection_mode 拉好商品。
+ */
+
+import * as React from 'react';
+import type { ProductGridData } from '../types';
+
+export interface ProductGridSectionProps {
+  data: ProductGridData;
+  /** 父组件预先拉好的商品数据 */
+  products?: Array<{
+    id: string;
+    handle: string;
+    title: string;
+    price?: { amount: string; currencyCode: string };
+    image?: { url: string; alt?: string };
+  }>;
+}
+
+export function ProductGridSection({ data, products }: ProductGridSectionProps): React.ReactElement {
+  const columns = data.columns ?? 3;
+  const list = products ?? [];
+
+  return (
+    <section style={{ padding: '64px 32px', maxWidth: 1280, margin: '0 auto' }}>
+      {data.title && (
+        <h2 style={{ fontSize: 'clamp(1.5rem, 3vw, 2rem)', margin: 0, fontWeight: 800 }}>{data.title}</h2>
+      )}
+      {data.subtitle && (
+        <p style={{ marginTop: 8, color: '#64748b', fontSize: 15 }}>{data.subtitle}</p>
+      )}
+      <div
+        style={{
+          marginTop: 24,
+          display: 'grid',
+          gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
+          gap: 24,
+        }}
+      >
+        {list.length === 0 ? (
+          <div
+            style={{
+              gridColumn: '1 / -1',
+              padding: '40px 0',
+              textAlign: 'center',
+              color: '#94a3b8',
+              fontSize: 14,
+            }}
+          >
+            {data.selection_mode === 'manual'
+              ? '（暂未选定商品）'
+              : '（暂无商品数据，编辑器预览模式不拉取真实数据）'}
+          </div>
+        ) : (
+          list.map((p) => (
+            <a
+              key={p.id}
+              href={`/products/${p.handle}`}
+              style={{
+                background: '#fff',
+                border: '1px solid #e2e8f0',
+                borderRadius: 10,
+                overflow: 'hidden',
+                textDecoration: 'none',
+                color: 'inherit',
+                display: 'block',
+              }}
+            >
+              {p.image && (
+                <img
+                  src={p.image.url}
+                  alt={p.image.alt || p.title}
+                  style={{ width: '100%', aspectRatio: '1 / 1', objectFit: 'cover', display: 'block' }}
+                />
+              )}
+              <div style={{ padding: 14 }}>
+                <div style={{ fontSize: 14, fontWeight: 600, color: '#0f172a' }}>{p.title}</div>
+                {p.price && (
+                  <div style={{ marginTop: 6, fontSize: 15, color: '#ea580c', fontWeight: 700 }}>
+                    {p.price.currencyCode === 'CNY' ? '¥' : p.price.currencyCode + ' '}
+                    {p.price.amount}
+                  </div>
+                )}
+              </div>
+            </a>
+          ))
+        )}
+      </div>
+    </section>
+  );
+}

package/src/page-schema/sections/RichText.tsx

@@ -0,0 +1,49 @@
+/**
+ * <RichTextSection> — 富文本
+ *
+ * P0：只支持 plain text + 简单换行；markdown 渲染留给商家自己用 marked 库或写成 html
+ * mode。等编辑器成熟后再上 markdown 渲染。
+ */
+
+import * as React from 'react';
+import type { RichTextData } from '../types';
+
+export interface RichTextSectionProps {
+  data: RichTextData;
+}
+
+const WIDTH_MAP: Record<NonNullable<RichTextData['max_width']>, string> = {
+  narrow: '640px',
+  normal: '880px',
+  wide: '1200px',
+};
+
+export function RichTextSection({ data }: RichTextSectionProps): React.ReactElement {
+  const maxWidth = WIDTH_MAP[data.max_width ?? 'normal'];
+
+  if (data.format === 'html') {
+    return (
+      <section style={{ padding: '48px 32px' }}>
+        <div
+          style={{ maxWidth, margin: '0 auto', lineHeight: 1.7, fontSize: 15.5, color: '#0f172a' }}
+          dangerouslySetInnerHTML={{ __html: data.body }}
+        />
+      </section>
+    );
+  }
+
+  // markdown / plain：按段落分割（双换行 = 新段落）
+  const paragraphs = data.body.split(/\n{2,}/);
+
+  return (
+    <section style={{ padding: '48px 32px' }}>
+      <div style={{ maxWidth, margin: '0 auto', lineHeight: 1.7, fontSize: 15.5, color: '#0f172a' }}>
+        {paragraphs.map((p, i) => (
+          <p key={i} style={{ margin: i === 0 ? '0' : '1em 0 0', whiteSpace: 'pre-line' }}>
+            {p}
+          </p>
+        ))}
+      </div>
+    </section>
+  );
+}

package/src/page-schema/sections/Spacer.tsx

@@ -0,0 +1,15 @@
+/**
+ * <SpacerSection> — 垂直留白
+ */
+
+import * as React from 'react';
+import type { SpacerData } from '../types';
+
+export interface SpacerSectionProps {
+  data: SpacerData;
+}
+
+export function SpacerSection({ data }: SpacerSectionProps): React.ReactElement {
+  const height = typeof data.height === 'number' ? `${data.height}px` : data.height;
+  return <div style={{ height }} aria-hidden />;
+}