@open-press/core/manuscript

文稿輔助工具

用於長篇章節流程的選擇性輔助工具。Sections 會遍歷一個已註冊的來源，並為每個章節發出一個 frame，且會根據內容長短自動分頁到多個 frames。Toc + TocArea 則能為您提供自動產生的目錄。

@open-press/core/manuscript 模組提供支援長篇章節、自動分頁與目錄生成的 React 元件與工具函數。主要適用於報告、論文與書籍等文件類型；固定版面之簡報或卡片設計應略過此模組。

Component Impl

# `<Sections>`

遍歷指定 MDX 來源並自動生成對應之 Frame 序列。處理內容溢出時會自動實例化新分頁。

import { Sections } from "@open-press/core/manuscript";

<Sections
  source="story"
  page?={SectionsPageComponent}
  opener?={SectionsOpenerComponent}
/>

屬性 (Props)

Name	Type	Default	Description
`source` required	`string`		於 `` 中註冊之來源識別碼 (`id`)。
`page`	`ComponentType<SectionsPageProps>`	`DefaultSectionPage`	單頁渲染元件。接收 `frameKey`、`chainId`、`pageIndex`、`totalPages`、`sectionSlug`、`sectionTitle`、`sectionTone` 等上下文屬性。
`opener`	`ComponentType<SectionsOpenerProps>`		章節開場頁（分隔頁）渲染元件。若提供，將於每章節首頁之前插入。

範例：客製化內容分頁

function ContentPage({
  frameKey, chainId, pageIndex, totalPages, sectionTitle,
}: SectionsPageProps) {
  return (
    <Frame frameKey={frameKey} role="document.content">
      <div className="flex h-full flex-col px-16 py-12">
        <main className="min-h-0 flex-1 text-[22px] leading-relaxed">
          <MdxArea chainId={chainId} />
        </main>
        <footer className="flex justify-between text-xs uppercase tracking-wide text-neutral-500">
          <span>{sectionTitle}</span>
          <span>{pageIndex + 1}/{totalPages}</span>
        </footer>
      </div>
    </Frame>
  );
}

<Press><Sections source="story" page={ContentPage} /></Press>

Component Impl

# `Chapters`

`<Sections>` 的別名元件。當內容層級語義為「章」(Chapter) 時使用，屬性介面與 `<Sections>` 完全一致。

import { Chapters } from "@open-press/core/manuscript";

Component Impl

# `DefaultSectionPage`

系統預設之章節分頁元件。內建標準的頁首、頁尾與 `<MdxArea>` 內容插槽實作。

import { DefaultSectionPage } from "@open-press/core/manuscript";

<DefaultSectionPage {...sectionsPageProps} />

Component Impl

# `<Toc>`

生成基於文件標題結構之目錄 (Table of Contents)。自動配置為 `<Frame>` 並支援跨頁溢出。

import { Toc } from "@open-press/core/manuscript";

<Toc
  source="story"
  maxLevel?={3}
  page?={TocPageComponent}
/>

屬性 (Props)

Name	Type	Default	Description
`source` required	`string`		提取標題層級之目標 MDX 來源標識符。
`maxLevel`	`number`	`3`	擷取標題之最大深度（如 `3` 表示提取 H1 至 H3）。
`page`	`ComponentType<TocPageProps>`		客製化目錄容器元件。預設實作會渲染標準 Frame 與 ``。

Component Impl

# `<TocArea>`

受管理的目錄內容插槽。為 `<MdxArea>` 針對目錄場景之特化封裝，必須於 `<Toc>` 客製頁面內部使用。

import { TocArea } from "@open-press/core/manuscript";

<TocArea
  chainId="toc:story"
  maxLevel?={3}
  overflow?="extend"
  className?
/>

屬性 (Props)

Name	Type	Default	Description
`chainId` required	`string`		系統生成之目錄鏈結識別碼（格式為 `toc:`）。
`maxLevel`	`number`	`3`	控制目錄清單輸出之標題深度。
`overflow`	`"extend" \| "truncate"`	`"extend"`	與 `MdxArea` 溢出處理語義一致。
`className`	`string`		附加至根 ` ` 元素之 CSS 類別。

實作注意事項

隱式 CSS 作用域：文稿生成的 <Frame> 預設帶有 role="manuscript.content" 或 role="manuscript.toc" 屬性，供主題樣式表作層疊選取。
內部鏈結綁定：目錄來源鏈結 (如 toc:story) 由引擎於建置階段遍歷標題自動產生，開發者不得手動寫入或註冊。
設計模式界線：若文件需要高度客製化的固定版面設計，應放棄使用 <Sections> 輔助工具，改採手動宣告 Frame 並結合 overflow="truncate" 的 <MdxArea> 實作。