docs: add 10 MDX pages for all components, text, and examples

2026-05-21 14:25:35 +08:00
parent 729e6ab287
commit 7b3afa245c
14 changed files with 308 additions and 16 deletions
@@ -0,0 +1,43 @@
+---
+title: 数据组件
+description: Folio / IndexBox / Factbox / RelatedArticles
+---
+
+## Folio
+
+版面页眉（页码 + 版名 + 日期），每个内页顶部使用。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| page | string | — | 页码，如 "A2" |
+| section | string | — | 版名，如 "要闻" |
+| date | string | — | 日期 |
+| publication | string | — | 报名 |
+
+## IndexBox
+
+头版内容索引框，告诉读者各版有什么。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| title | string | "Inside" | 标题 |
+| items | `Array<{ page, title, headline? }>` | — | 索引条目 |
+
+## Factbox
+
+嵌入正文的信息框（数据、时间线、人物简介等）。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| title | string | — | 标题 |
+| span | number | — | 跨栏数 |
+| variant | "default" \| "highlight" \| "timeline" | "default" | 样式变体 |
+
+## RelatedArticles
+
+"相关报道" 列表。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| title | string | "Related" | 标题 |
+| articles | `Array<{ title, href, category? }>` | — | 文章列表 |
@@ -0,0 +1,33 @@
+---
+title: Footer · Sidebar · Banner
+description: 页脚、侧边栏、突发新闻横幅
+---
+
+## Footer
+
+报纸页脚/版权信息区。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| copyright | string | — | 版权文字 |
+| edition | string | — | 版次 |
+| links | `Array<{ label, href }>` | — | 底部链接 |
+
+## NewsSidebar
+
+侧边栏内容区（天气、股票、快讯摘要等）。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| span | number | 6 | 占用列数 |
+| position | "left" \| "right" | "right" | 位置 |
+| divider | boolean | false | 是否显示分隔线 |
+
+## BreakingNewsBanner
+
+突发新闻横幅，全宽显示。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| label | string | "BREAKING" | 标签文字 |
+| children | ReactNode | — | 新闻内容 |
@@ -0,0 +1,46 @@
+---
+title: Layout 布局
+description: Layout / Section / Article / Layer 四个基础布局组件
+---
+
+## Layout
+
+顶层容器，提供 24 列栅格 Context。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| columns | number | 24 | 栅格总列数 |
+| maxWidth | string | "1280px" | 最大宽度 |
+| padding | string | "var(--nui-space-6)" | 内边距 |
+| theme | "light" \| "dark" | — | 主题 |
+
+## Section
+
+CSS Grid 栅格区域，内部对象通过 `grid-column: span N` 跨栏。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| columns | number | — | 栅格列数（≤ Layout.columns） |
+| gap | string | "var(--nui-gutter)" | 间距 |
+| breakable | boolean | true | 是否允许分页断开 |
+| divider | "none" \| "top" \| "bottom" \| "both" | "none" | 分隔线 |
+| responsive | `{ sm?: number; md?: number; lg?: number }` | — | 响应式列数 |
+
+## Article
+
+文章块，通过 `grid-column: span N` 跨栏。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| span | number | — | 跨栏数 |
+| breakable | boolean | true | 是否允许分页断开 |
+
+## Layer
+
+浮动层，脱离栅格流。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| position | "absolute" \| "fixed" \| "sticky" | "absolute" | 定位方式 |
+| top / left / right / bottom | string \| number | — | 位置 |
+| zIndex | number | — | 层级 |
@@ -1,4 +1,4 @@
 {
  "title": "Components",
-  "pages": ["article", "masthead", "rule", "media"]
+  "pages": ["layout", "article", "masthead", "rule", "media", "footer", "data"]
 }
@@ -0,0 +1,11 @@
+---
+title: Blackletter 头版
+description: 德式哥特体报纸头版
+---
+
+完整 Blackletter 头版 demo 请访问 [/examples/blackletter-frontpage](/examples/blackletter-frontpage)。
+
+特点：
+- UnifrakturMaguntia 哥特体报头
+- 6 + 18 两栏布局
+- 德语内容
@@ -1,4 +1,4 @@
 {
  "title": "Examples",
-  "pages": ["spanning", "responsive"]
+  "pages": ["spanning", "responsive", "nyt-frontpage", "blackletter"]
 }
@@ -0,0 +1,13 @@
+---
+title: NYT 头版
+description: 经典美式严肃风报纸头版
+---
+
+完整 NYT 风格头版 demo 请访问 [/examples/nyt-frontpage](/examples/nyt-frontpage)。
+
+特点：
+- Cormorant Garamond 报头
+- 5 + 14 + 5 三栏布局
+- 3 栏 BodyText + Drop Cap
+- PullQuote 居中
+- Briefs 短讯栏
@@ -0,0 +1,31 @@
+---
+title: BodyText
+description: 正文组件，支持多栏文字流和首字下沉
+---
+
+## API
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| weight | "High" \| "Medium" \| "Low" | "Medium" | 视觉权重 |
+| columns | 1 \| 2 \| 3 \| 4 | 1 | 多栏文字流 |
+| columnWidth | string | — | 栏目标宽度 |
+| columnFill | "auto" \| "balance" | "balance" | 栏填充模式 |
+| dropCap | boolean | false | 首字下沉 |
+| span | number | — | 跨栏数 |
+
+## 多栏文字流
+
+设置 `columns={3}` 启用 CSS Multi-column，文字自动 reflow 到 3 栏，栏间有 1px hairline 分隔。
+
+## 首字下沉
+
+设置 `dropCap` 启用 `::first-letter` 首字下沉效果（4.2em Display 字体）。
+
+## 排版细节
+
+默认启用：
+- 段间无空行 + 第二段起首行缩进 1em
+- Old-style figures（3/5/7 有下伸笔）
+- Hanging punctuation（引号悬挂）
+- Column rule（栏间 hairline）
@@ -0,0 +1,50 @@
+---
+title: Byline · Dateline · Caption
+description: 署名、发稿地、图片说明
+---
+
+## Byline
+
+署名，Inter small-caps 格式。
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| children | ReactNode | 如 "By Alice Smith" |
+
+## Dateline
+
+发稿地，Inter small-caps + 粗体。
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| children | ReactNode | 如 "LONDON —" |
+
+## Caption
+
+图片说明，italic 衬线 13px。
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| credit | string | 摄影师署名（small-caps 渲染） |
+| children | ReactNode | 说明文字 |
+
+## AuthorCard
+
+作者简介卡片。
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| name | string | 姓名 |
+| role | string | 职位 |
+| bio | string | 简介 |
+| avatar | string | 头像 URL |
+| email | string | 邮箱 |
+
+## JumpLine
+
+跨版续转标注。
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| direction | "to" \| "from" | 方向 |
+| page | string | 目标版面，如 "A6" |
@@ -0,0 +1,19 @@
+---
+title: Headline
+description: 标题组件，High/Medium/Low 三档视觉权重
+---
+
+## API
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| weight | "High" \| "Medium" \| "Low" | "High" | 视觉权重 |
+| span | number | — | 跨栏数 |
+| as | "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" | 自动 | HTML 标签 |
+| align | "left" \| "center" \| "right" | — | 对齐 |
+
+## 视觉权重
+
+- **High**: 48–72px, weight 600, line-height 1.05, Source Serif 4 Display
+- **Medium**: 32–40px, weight 600, line-height 1.1
+- **Low**: 22–26px, weight 500, line-height 1.2
@@ -0,0 +1,15 @@
+---
+title: Kicker
+description: 小帽体标签，朱红 accent 色
+---
+
+## API
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| children | ReactNode | — | 标签文字 |
+
+## 说明
+
+使用 Inter 字体 + 真 OpenType small-caps + 朱红色（`--nui-accent-primary`）。
+常用于 Headline 上方的栏目标识。
@@ -1,4 +1,4 @@
 {
  "title": "Text",
-  "pages": ["index"]
+  "pages": ["index", "headline", "bodytext", "kicker", "quote", "byline"]
 }
@@ -0,0 +1,21 @@
+---
+title: Quote
+description: 引用组件，block 和 inline 两种变体
+---
+
+## API
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| variant | "block" \| "inline" | "block" | 变体 |
+| weight | "High" \| "Medium" | "Medium" | 视觉权重 |
+| span | number | — | 跨栏数 |
+| cite | string | — | 引用来源 URL |
+
+## Block Quote
+
+左缩进 1.5em，**无 border-left**（报纸传统）。
+
+## Inline Quote
+
+渲染为 `<em>` italic，不加引号（报纸传统）。