@open-press/core/manuscript

Manuscript Utilities

Optional utilities for long-form chapter flows. Sections traverses a registered source and emits a frame for each section, automatically paginating into multiple frames based on length. Toc + TocArea give you an auto-generated table of contents.

The @open-press/core/manuscript module provides React components and utility functions that support long-form chapters, automatic pagination, and table of contents generation. It is primarily applicable for document types like reports, papers, and books; fixed-layout presentation or card designs should bypass this module.

Component Impl

# `<Sections>`

Traverses the specified MDX source and automatically generates a sequence of corresponding Frames. It automatically instantiates new pages when handling content overflow.

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

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

Props

Name	Type	Default	Description
`source` required	`string`		The source identifier (`id`) registered in ``.
`page`	`ComponentType<SectionsPageProps>`	`DefaultSectionPage`	Single page rendering component. Receives context props like `frameKey`, `chainId`, `pageIndex`, `totalPages`, `sectionSlug`, `sectionTitle`, `sectionTone`, etc.
`opener`	`ComponentType<SectionsOpenerProps>`		Section opener page (separator page) rendering component. If provided, it is inserted before the first page of each section.

Example: Customized Content Pagination

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`

Alias component for `<Sections>`. Used when the content hierarchy semantics represent 'Chapters'; the prop interface is perfectly identical to `<Sections>`.

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

Component Impl

# `DefaultSectionPage`

The system's default section pagination component. Includes built-in implementations of standard headers, footers, and the `<MdxArea>` content slot.

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

<DefaultSectionPage {...sectionsPageProps} />

Component Impl

# `<Toc>`

Generates a Table of Contents based on the document's heading structure. Automatically configured as a `<Frame>` and supports cross-page overflow.

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

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

Props

Name	Type	Default	Description
`source` required	`string`		Target MDX source identifier to extract heading levels from.
`maxLevel`	`number`	`3`	Maximum depth of headings to extract (e.g., `3` means extract H1 to H3).
`page`	`ComponentType<TocPageProps>`		Custom TOC container component. The default implementation renders a standard Frame and ``.

Component Impl

# `<TocArea>`

Managed TOC content slot. A specialized wrapper of `<MdxArea>` tailored for TOC scenarios; must be used inside a customized `<Toc>` page.

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

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

Props

Name	Type	Default	Description
`chainId` required	`string`		System-generated TOC chain identifier (format: `toc:`).
`maxLevel`	`number`	`3`	Controls heading depth of the TOC list output.
`overflow`	`"extend" \| "truncate"`	`"extend"`	Consistent with `MdxArea` overflow handling semantics.
`className`	`string`		CSS class attached to the root ` ` element.

Implementation Notes

Implicit CSS Scoping: The <Frame> generated by manuscripts defaults to having a role="manuscript.content" or role="manuscript.toc" attribute for theme stylesheets to cascade selectors against.
Internal Chain Binding: TOC source chains (like toc:story) are automatically generated by the engine traversing headings during the build phase; developers must not manually write or register them.
Design Pattern Boundaries: If the document requires highly customized fixed-layout design, you should abandon the <Sections> utility and manually declare Frames coupled with <MdxArea> implementations using overflow="truncate".