@core / blocks

1.0.0 ▾

1.0.0

已验证MIT

GitHub

页面区块：15 个无障碍版块（首屏、价格、带 JSON-LD 的 FAQ 等）、后台编辑器和可扩展注册表

代码25 个文件上下文约 681 个 token扫描通过

约 681 个 token→ src/lib/blocks/AGENTS.md→ .cursor/rules/genpm-core-blocks.mdc

这正是你的 AI 在 src/lib/blocks 中工作时读取的内容。不会向其上下文添加其他任何内容。

@core/blocks — rules for AI agents

Purpose

Page sections that editors combine from the admin: hero, features, benefits, testimonials, logos, pricing, FAQ (with FAQPage JSON-LD), call to action, gallery, video, stats, comparison, guarantee, rich text and form. Each block is a zod schema + editor fields + a React component. Other packages and kits add their own blocks (product grid, latest posts…) to the same registry. Blocks are stored as JSON inside @core/content entries; no tables of its own.

Map

index.ts — defineBlock, createBlockRegistry, coreBlocks (and each block), RenderBlocks, collectMediaIds.
core/*.ts — one file per block. parts.ts — Section, Heading, Img, CtaLink, JsonLd for new blocks.
media.ts — loadBlockMedia(blocks, registry) (server: one query to @core/media).
editor.ts — 'use client': blocksRenderer(blockMeta(registry)) for AdminApp. blocks.css — styles on @core/ui tokens.

Integration

Create src/genpm/blocks.ts: export const blocks = createBlockRegistry([...coreBlocks /*, kit blocks */]);
Add a field to a content collection: schema blocks: blocks.schema, admin field blocks.field('blocks', 'Sections').
Admin: compute blockMeta(blocks) on the server and pass it to the client component that renders <AdminApp renderers={{ blocks: blocksRenderer(meta), /* richText, media… */ }} /> (never import the registry in client code).

Page (server component):

const media = await loadBlockMedia(page.data.blocks, blocks);
return <RenderBlocks blocks={page.data.blocks} registry={blocks} media={media}
  renderForm={(key) => <Form formKey={key} />} embeds={hasConsent('marketing') ? 'iframe' : 'link'} />;

Styles: import src/lib/ui/ui.css then src/lib/blocks/blocks.css in the root layout.
Verify: a page with every block passes axe and has one h1; a block with an unknown type renders nothing and warns in dev.

Conventions

A new block = new file with defineBlock + entry in the registry. Never add if (type === …) to RenderBlocks.
Use Section and Heading with ctx.level (items one level below); only blocks with pageTitle may become the h1.
Images are media ids resolved with loadBlockMedia; links go through the href schema (no javascript:).
Text in blocks is plain text; use the rich-text block for formatting.

Don't

Don't render user HTML (dangerouslySetInnerHTML) except via JsonLd, which escapes <, > and &.
Don't load video iframes without marketing consent (embeds: 'link' is the default).
Don't invent testimonials, ratings or statistics; the editor help texts remind users these must be real and verifiable.

# @core/blocks — rules for AI agents

## Purpose
Page sections that editors combine from the admin: hero, features, benefits, testimonials, logos, pricing, FAQ (with
FAQPage JSON-LD), call to action, gallery, video, stats, comparison, guarantee, rich text and form. Each block is a
zod schema + editor fields + a React component. Other packages and kits add their own blocks (product grid, latest
posts…) to the same registry. Blocks are stored as JSON inside @core/content entries; no tables of its own.

## Map
- `index.ts` — `defineBlock`, `createBlockRegistry`, `coreBlocks` (and each block), `RenderBlocks`, `collectMediaIds`.
- `core/*.ts` — one file per block. `parts.ts` — `Section`, `Heading`, `Img`, `CtaLink`, `JsonLd` for new blocks.
- `media.ts` — `loadBlockMedia(blocks, registry)` (server: one query to @core/media).
- `editor.ts` — `'use client'`: `blocksRenderer(blockMeta(registry))` for `AdminApp`. `blocks.css` — styles on @core/ui tokens.

## Integration
1. Create `src/genpm/blocks.ts`: `export const blocks = createBlockRegistry([...coreBlocks /*, kit blocks */]);`
2. Add a field to a content collection: schema `blocks: blocks.schema`, admin field `blocks.field('blocks', 'Sections')`.
3. Admin: compute `blockMeta(blocks)` on the server and pass it to the client component that renders
   `<AdminApp renderers={{ blocks: blocksRenderer(meta), /* richText, media… */ }} />` (never import the registry in client code).
4. Page (server component):
   ```tsx
   const media = await loadBlockMedia(page.data.blocks, blocks);
   return <RenderBlocks blocks={page.data.blocks} registry={blocks} media={media}
     renderForm={(key) => <Form formKey={key} />} embeds={hasConsent('marketing') ? 'iframe' : 'link'} />;
   ```
5. Styles: import `src/lib/ui/ui.css` then `src/lib/blocks/blocks.css` in the root layout.
6. Verify: a page with every block passes axe and has one `h1`; a block with an unknown type renders nothing and warns in dev.

## Conventions
- A new block = new file with `defineBlock` + entry in the registry. Never add `if (type === …)` to `RenderBlocks`.
- Use `Section` and `Heading` with `ctx.level` (items one level below); only blocks with `pageTitle` may become the `h1`.
- Images are media ids resolved with `loadBlockMedia`; links go through the `href` schema (no `javascript:`).
- Text in blocks is plain text; use the `rich-text` block for formatting.

## Don't
- Don't render user HTML (`dangerouslySetInnerHTML`) except via `JsonLd`, which escapes `<`, `>` and `&`.
- Don't load video iframes without marketing consent (`embeds: 'link'` is the default).
- Don't invent testimonials, ratings or statistics; the editor help texts remind users these must be real and verifiable.

应用 .genpmignore 后将被注入的确切目录树。固定于

src/lib/blocks/render.ts只读 · a255d6d

// Render de una lista de bloques. Sin condicionales por tipo: cada bloque se pinta con el componente de su definición.
import { createElement as h, Fragment, type ReactNode } from 'react';
import type { ResolvedImage } from '../rich-text/index.ts';
import type { BlockContext, BlockInstance, BlockRegistry } from './define.ts';

const dev = () => typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production';

export type RenderBlocksProps = {
  blocks: BlockInstance[] | null | undefined;
  registry: BlockRegistry;
  /** Imágenes de @core/media ya resueltas (`await loadBlockMedia(blocks, registry)`). */
  media?: Record<string, ResolvedImage>;
  /** `true` si la página ya tiene su `h1` fuera de los bloques: ningún bloque usará `h1`. */
  hasPageTitle?: boolean;
  /** Nivel de encabezado de los bloques (2 por defecto). */
  level?: 2 | 3 | 4;
  embeds?: 'link' | 'iframe';
  siteHost?: string;
  renderForm?: (formKey: string) => ReactNode;
  /** Aviso para bloques desconocidos o inválidos (por defecto `console.warn` solo en desarrollo). */
  onSkip?: (block: BlockInstance, reason: 'unknown' | 'invalid') => void;
};

/** `<RenderBlocks blocks={page.data.blocks} registry={blocks} media={media} />` */
export function RenderBlocks(p: RenderBlocksProps): ReactNode {
  const image = (id: unknown): ResolvedImage | null => (typeof id === 'string' && p.media?.[id]) || null;
  const skip = p.onSkip ?? ((b, reason) => dev() && console.warn(`[blocks] skipped ${reason} block "${b.type}" (${b.id})`));
  let titleUsed = !!p.hasPageTitle;
  let first = true;
  const out: ReactNode[] = [];
  for (const b of p.blocks ?? []) {
    if (b.hidden) continue;
    const def = p.registry.get(b.type);
    if (!def) {
      skip(b, 'unknown');
      continue;
    }
    const parsed = def.schema.safeParse(b.data);
    if (!parsed.success) {
      skip(b, 'invalid');
      continue;
    }
    const isTitle = !titleUsed && !!def.pageTitle?.(parsed.data);
    if (isTitle) titleUsed = true;
    const ctx: BlockContext = {
      id: `b-${b.id.replace(/[^\w-]/g, '')}`,
      level: isTitle ? 1 : (p.level ?? 2),
      image,
      embeds: p.embeds ?? 'link',
      first,
      ...(p.siteHost && { siteHost: p.siteHost }),
      ...(p.renderForm && { renderForm: p.renderForm }),
    };
    first = false;
    out.push(h(Fragment, { key: b.id }, h(def.Component, { data: parsed.data, ctx })));
  }
  return h(Fragment, null, ...out);
}