@shopbb/helium 0.8.0 → 0.9.0

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

package/src/page-schema/types.ts

@@ -0,0 +1,286 @@
+/**
+ * Page Schema — 装修页面的结构化数据模型
+ *
+ * 一个 Page 是若干 Section 的有序数组。每个 Section 是 (type, data) 的结构化值，
+ * 不是任意 React 代码。这样 agent / 编辑器 / 渲染器都能精准操作。
+ *
+ * 设计原则：
+ *   1. 强 schema：每个 type 的 data 字段固定，agent 不能"乱发挥"
+ *   2. stable id：每个 section 有唯一 id，编辑器选中、agent 引用都靠它
+ *   3. 可演进：新加 section type 只需扩 SectionType 联合 + 实现对应 React 组件
+ *   4. 反规范化：data 是平铺字段而不是嵌套结构，方便 agent 修改单个属性
+ */
+
+// ============================================================
+// 基础类型
+// ============================================================
+
+export type SectionType =
+  | 'hero'
+  | 'product-grid'
+  | 'banner'
+  | 'rich-text'
+  | 'image'
+  | 'spacer';
+
+/** 通用 section wrapper */
+export interface Section<T extends SectionType = SectionType, D = unknown> {
+  /** 唯一 ID，stable，编辑器与 agent 都引用它 */
+  id: string;
+  /** Section 类型 */
+  type: T;
+  /** 类型对应的数据字段 */
+  data: D;
+  /** 是否可见。隐藏的 section 不渲染但保留在 schema 里（方便商家临时下线某块） */
+  visible: boolean;
+}
+
+// ============================================================
+// 每种 section 的 data 字段
+// ============================================================
+
+export interface HeroData {
+  /** 大标题 */
+  headline: string;
+  /** 副标题 */
+  subheadline?: string;
+  /** 背景图 URL */
+  background_image?: string;
+  /** 背景色，hex 或 css 颜色 */
+  background_color?: string;
+  /** 文字颜色 */
+  text_color?: string;
+  /** 主 CTA 按钮文案 */
+  cta_label?: string;
+  /** 主 CTA 链接 */
+  cta_link?: string;
+  /** 副 CTA 按钮文案 */
+  secondary_cta_label?: string;
+  /** 副 CTA 链接 */
+  secondary_cta_link?: string;
+  /** 高度 */
+  height?: 'small' | 'medium' | 'large' | 'full';
+  /** 文字对齐 */
+  text_align?: 'left' | 'center' | 'right';
+}
+
+export interface ProductGridData {
+  /** 标题（可选） */
+  title?: string;
+  /** 副标题 */
+  subtitle?: string;
+  /** 选商品的方式 */
+  selection_mode: 'manual' | 'collection' | 'newest' | 'top-selling';
+  /** manual 模式下，指定的 product handle 列表 */
+  product_handles?: string[];
+  /** collection 模式下，指定的 collection handle */
+  collection_handle?: string;
+  /** 自动模式下取多少个 */
+  limit?: number;
+  /** 一行几列 */
+  columns?: 2 | 3 | 4;
+}
+
+export interface BannerData {
+  /** 主文案 */
+  text: string;
+  /** 链接（可选） */
+  link?: string;
+  /** 链接打开文案，例如"立即查看" */
+  link_label?: string;
+  /** 背景色 */
+  background_color?: string;
+  /** 文字色 */
+  text_color?: string;
+  /** 关闭按钮（用户能 dismiss） */
+  dismissible?: boolean;
+}
+
+export interface RichTextData {
+  /** Markdown / HTML 文本 */
+  body: string;
+  /** 渲染模式 */
+  format?: 'markdown' | 'html';
+  /** 最大宽度（约束阅读体验） */
+  max_width?: 'narrow' | 'normal' | 'wide';
+}
+
+export interface ImageData {
+  /** 图片 URL */
+  url: string;
+  /** alt 文本（无障碍） */
+  alt?: string;
+  /** 点击跳转链接 */
+  link?: string;
+  /** 宽度模式 */
+  width?: 'full' | 'normal' | 'narrow';
+}
+
+export interface SpacerData {
+  /** 高度（像素或者 css 单位字符串） */
+  height: number | string;
+}
+
+// ============================================================
+// 联合类型
+// ============================================================
+
+export type HeroSection = Section<'hero', HeroData>;
+export type ProductGridSection = Section<'product-grid', ProductGridData>;
+export type BannerSection = Section<'banner', BannerData>;
+export type RichTextSection = Section<'rich-text', RichTextData>;
+export type ImageSection = Section<'image', ImageData>;
+export type SpacerSection = Section<'spacer', SpacerData>;
+
+export type AnySection =
+  | HeroSection
+  | ProductGridSection
+  | BannerSection
+  | RichTextSection
+  | ImageSection
+  | SpacerSection;
+
+// ============================================================
+// Page 与全局配置
+// ============================================================
+
+/** 全局样式（应用到整个 page 的层级） */
+export interface PageGlobalStyle {
+  primary_color?: string;
+  background_color?: string;
+  font_family?: 'system' | 'serif' | 'sans-serif' | string;
+}
+
+export interface Page {
+  /** 页面标识，例如 'home' / 'about' / 'collections/featured' */
+  slug: string;
+  /** 浏览器标题（可选，缺省用 store name） */
+  title?: string;
+  /** Section 数组，按顺序渲染 */
+  sections: AnySection[];
+  /** 全局样式 */
+  global_style?: PageGlobalStyle;
+  /** Schema 版本，用于将来升级时迁移 */
+  schema_version: 1;
+}
+
+// ============================================================
+// Helper：生成 section ID
+// ============================================================
+
+export function newSectionId(type: SectionType): string {
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `sec_${type.replace('-', '_')}_${rand}`;
+}
+
+// ============================================================
+// 默认 data —— 商家新增某 type 的 section 时用作初始值
+// ============================================================
+
+export const DEFAULT_DATA: { [K in SectionType]: AnySection['data'] } = {
+  hero: {
+    headline: '欢迎来到我们的店铺',
+    subheadline: '精选商品 全场包邮',
+    height: 'medium',
+    text_align: 'center',
+    background_color: '#0f172a',
+    text_color: '#ffffff',
+    cta_label: '立刻购买',
+    cta_link: '/products',
+  } as HeroData,
+  'product-grid': {
+    title: '精选商品',
+    selection_mode: 'newest',
+    limit: 6,
+    columns: 3,
+  } as ProductGridData,
+  banner: {
+    text: '满 200 减 20，限时优惠',
+    background_color: '#f97316',
+    text_color: '#ffffff',
+  } as BannerData,
+  'rich-text': {
+    body: '在这里写一段品牌故事或说明文字。',
+    format: 'markdown',
+    max_width: 'normal',
+  } as RichTextData,
+  image: {
+    url: 'https://placehold.co/1200x400',
+    alt: '广告图',
+    width: 'full',
+  } as ImageData,
+  spacer: {
+    height: 40,
+  } as SpacerData,
+};
+
+/** 创建一个新 section（带默认 data） */
+export function createSection<T extends SectionType>(type: T): AnySection {
+  return {
+    id: newSectionId(type),
+    type,
+    data: { ...(DEFAULT_DATA[type] as object) } as any,
+    visible: true,
+  } as AnySection;
+}
+
+/** 创建一个空白 page */
+export function createEmptyPage(slug: string): Page {
+  return {
+    slug,
+    sections: [],
+    schema_version: 1,
+  };
+}
+
+// ============================================================
+// 校验
+// ============================================================
+
+const REQUIRED_FIELDS: { [K in SectionType]: string[] } = {
+  hero: ['headline'],
+  'product-grid': ['selection_mode'],
+  banner: ['text'],
+  'rich-text': ['body'],
+  image: ['url'],
+  spacer: ['height'],
+};
+
+/** 校验一个 section 数据完整性。返回错误列表，空数组表示合法 */
+export function validateSection(section: AnySection): string[] {
+  const errs: string[] = [];
+  if (!section.id) errs.push('id_required');
+  if (!section.type) errs.push('type_required');
+  const required = REQUIRED_FIELDS[section.type];
+  if (!required) {
+    errs.push(`unknown_section_type:${section.type}`);
+    return errs;
+  }
+  const data = section.data as unknown as Record<string, unknown>;
+  for (const f of required) {
+    if (data[f] == null || data[f] === '') {
+      errs.push(`missing_field:${section.type}.${f}`);
+    }
+  }
+  return errs;
+}
+
+/** 校验整个 page */
+export function validatePage(page: Page): string[] {
+  const errs: string[] = [];
+  if (!page.slug) errs.push('slug_required');
+  if (page.schema_version !== 1) errs.push(`unknown_schema_version:${page.schema_version}`);
+  if (!Array.isArray(page.sections)) {
+    errs.push('sections_must_be_array');
+    return errs;
+  }
+  const seenIds = new Set<string>();
+  for (let i = 0; i < page.sections.length; i++) {
+    const s = page.sections[i];
+    if (seenIds.has(s.id)) errs.push(`duplicate_section_id:${s.id}`);
+    seenIds.add(s.id);
+    const secErrs = validateSection(s);
+    errs.push(...secErrs.map((e) => `section[${i}]:${e}`));
+  }
+  return errs;
+}

package/src/react.tsx

@@ -274,6 +274,39 @@ function escapeHtml(s: string): string {
 /**
  * 把 head + react stream + tail 拼成一个 ReadableStream<Uint8Array>
  */
+// ============================================================
+// Page Schema re-export
+// ============================================================
+// 结构化页面渲染。Admin 编辑器与 storefront 共用同一份组件。
+export {
+  PageRenderer,
+  HeroSection,
+  ProductGridSection,
+  BannerSection,
+  RichTextSection,
+  ImageSection,
+  SpacerSection,
+  createSection,
+  createEmptyPage,
+  validateSection,
+  validatePage,
+  DEFAULT_DATA,
+  newSectionId,
+} from './page-schema';
+export type {
+  Page,
+  PageGlobalStyle,
+  AnySection,
+  SectionType,
+  HeroData,
+  ProductGridData,
+  BannerData,
+  RichTextData,
+  ImageData,
+  SpacerData,
+  PageRendererProps,
+} from './page-schema';
+
 // ============================================================
 // Tracking SDK re-export
 // ============================================================