# Satzstrom Primitives Reference

`@satzstrom/primitives` provides the public React components for physical pages, flowing composition, document structure, and render-ready content. Design and ordinary components stay under the author's control.

```tsx
import { Document, Page, PageMaster } from '@satzstrom/primitives';
```

Every direct child of `Document` is a fixed `Page` or flowing `PageMaster`. Both may be combined in one document.

## Document

`Document(props: DocumentProps)` is the document root. It defines language, reading direction, PDF metadata, and optional accessible labels.

| Prop        | Type                          | Required | Meaning                                |
| ----------- | ----------------------------- | -------- | -------------------------------------- |
| `children`  | `ReactNode`                   | yes      | Fixed pages and page masters.          |
| `title`     | `string`                      | yes      | Document title and PDF metadata.       |
| `author`    | `string`                      | no       | PDF author.                            |
| `subject`   | `string`                      | no       | PDF subject.                           |
| `keywords`  | `string[]`                    | no       | PDF search terms.                      |
| `lang`      | `string`                      | no       | Document language; defaults to `de`.   |
| `dir`       | `"ltr" \| "rtl"`              | no       | Reading direction; defaults to `ltr`.  |
| `bookmarks` | `SequenceDefinition<boolean>` | no       | Sequence used for PDF bookmarks.       |
| `labels`    | `DocumentLabels`              | no       | Overrides localized accessible labels. |
| `className` | `string`                      | no       | CSS class of the document root.        |

```tsx
<Document title="Invoice 2026-0718" author="Brückner Studio" lang="en">
  <Page size="A4">…</Page>
</Document>
```

## Page

`Page(props: PageProps)` creates exactly one freely composed physical page. Its children can be static or a render function receiving `page` and `pages`. It also accepts normal `section` props except `children`.

| Prop          | Type                                        | Required | Meaning                                                        |
| ------------- | ------------------------------------------- | -------- | -------------------------------------------------------------- |
| `children`    | `ReactNode \| ((PageContext) => ReactNode)` | yes      | Page content or page-value render function.                    |
| `size`        | `PageSizeName \| { width; height }`         | no       | Paper size; defaults to A4. Custom dimensions use millimetres. |
| `orientation` | `"portrait" \| "landscape"`                 | no       | Page orientation.                                              |
| `bleed`       | `number`                                    | no       | Non-negative bleed in millimetres.                             |
| `cropMarks`   | `boolean`                                   | no       | Enables crop marks.                                            |
| `className`   | `string`                                    | no       | CSS class of the physical page.                                |

## PageMaster

`PageMaster(props: PageMasterProps)` flows its children through a recurring React page frame and creates as many pages as necessary. `layout` is a `ComponentType<PageLayoutProps>` that receives `children`, `page`, and `pages`; it must render `children` exactly once.

| Prop          | Type                             | Required | Meaning                         |
| ------------- | -------------------------------- | -------- | ------------------------------- |
| `children`    | `ReactNode`                      | yes      | Flowing content.                |
| `layout`      | `ComponentType<PageLayoutProps>` | yes      | Recurring page frame.           |
| `size`        | `PageSettings["size"]`           | no       | Paper size for generated pages. |
| `orientation` | `PageSettings["orientation"]`    | no       | Shared orientation.             |
| `bleed`       | `number`                         | no       | Bleed in millimetres.           |
| `cropMarks`   | `boolean`                        | no       | Enables crop marks.             |
| `className`   | `string`                         | no       | CSS class of generated pages.   |

```tsx
function ReportPage({ children, page, pages }: PageLayoutProps) {
  return (
    <>
      <header>Annual report</header>
      <main>{children}</main>
      <footer>
        {page} / {pages}
      </footer>
    </>
  );
}

<PageMaster layout={ReportPage} size="A4">
  <h1>Introduction</h1>
  <p>This content flows across every required page.</p>
</PageMaster>;
```

## PageBreak and RepeatBox

`PageBreak()` forces the following flowing content in a `PageMaster` to begin on a new page.

`RepeatBox` marks a box whose border, background, and padding repeat on every fragment while its content continues without duplication. Its optional `as` prop chooses the rendered element and defaults to `div`; remaining props are those of that element.

## Numbering, contents, and references

`defineSequence({ name, titleRequired? })` creates an immutable independent numbering system for chapters, figures, or tables.

`Sequence` registers an entry. Its required `sequence` prop selects the definition and its required render-function `children` receives `number`, `title`, and `depth`. Optional props are `id`, `title`, and the accessible `numberLabel`. A title is required when the definition uses `titleRequired: true`.

```tsx
const chapters = defineSequence({ name: 'chapters', titleRequired: true });

<Sequence sequence={chapters} id="results" title="Results">
  {({ number, title }) => (
    <h2>
      {number} {title}
    </h2>
  )}
</Sequence>;
```

`Contents` creates a contents list from a required `sequence`, including final numbers and pages. `className` styles the default list. With `asChild`, it passes `entries` to exactly one custom React element.

`Ref` links to the HTML ID in required `target` and displays `number`, `title`, or `page` through its optional `value`, which defaults to `number`. It also accepts `className`.

## Footnote and Math

`Footnote({ children, label? })` places a numbered call in the text and moves its content to the foot of the appropriate page.

`Math({ children, display?, label? })` renders a KaTeX string as visible HTML and accessible MathML. `display` creates a separate equation row and `label` provides a stable accessible label.

## Markdown

`Markdown({ children, labels? })` renders GitHub-Flavored Markdown with tables, footnotes, and mathematics. Raw HTML is deliberately skipped.

## useRenderReady

`useRenderReady(ready: boolean)` delays measurement and rendering while asynchronous browser content is incomplete. Call it in the component that owns the asynchronous state. An outstanding wait is cleared when that component unmounts.

## Markdown navigation

- [CLI reference](/docs/cli.md)
- [MCP reference](/docs/mcp.md)
- [Quickstart](/quickstart.md)
- [Complete docs index](/docs/llms.txt)
- [Complete Markdown index](/llms.txt)